API reference

Account & API keys

Manage your account information, credits, and API keys programmatically.

Get account info

GET/v1/account

Retrieve your account details, credit balance, and usage statistics.

Response

{
  "success": true,
  "data": {
    "account": {
      "user_id": "user_a1b2c3d4e5f60718293a4b5c",
      "email": "user@example.com",
      "name": "John Doe",
      "plan": "professional",
      "status": "active",
      "created_at": "2025-06-15T10:00:00Z",
      "is_admin": false,
      "email_delivery": {
        "deliverable": true
      }
    },
    "credits": {
      "balance": 24500,
      "used_this_month": 500,
      "monthly_allowance": 25000,
      "next_reset": "2026-03-01T00:00:00.000Z"
    },
    "usage": {
      "current_month": {
        "jobs_count": 12,
        "emails_verified": 4500,
        "emails_valid": 3800,
        "emails_invalid": 450,
        "emails_risky": 180,
        "emails_unknown": 70
      },
      "period": { "start": "2026-02-01", "end": "2026-02-28" }
    },
    "api_keys": [
      {
        "key_id": "key_1a2b3c4d5e6f7a8b",
        "name": "Production",
        "status": "active",
        "created_at": "2025-06-15T10:00:00Z",
        "last_used_at": "2026-02-03T14:30:00Z",
        "key_preview": "ev_****cdEf"
      }
    ],
    "recent_jobs": [
      {
        "job_id": "9f8f6d2e-4c1b-4f6e-9a3b-2d1e5c7a8b90",
        "status": "completed",
        "total_emails": 1000,
        "processed_emails": 1000,
        "progress_percent": 100,
        "created_at": "2026-02-03T14:30:00Z",
        "completed_at": "2026-02-03T14:35:42Z"
      }
    ],
    "rate_limits": {
      "requests_per_minute": 300,
      "enforced": true
    }
  }
}

monthly_allowance reflects your plan's credit grant: 100 (Free), 5,000 (Starter), 25,000 (Professional), 100,000 (Business), 500,000 (Enterprise).

credits.next_reset is present only on a paid plan with a current billing period — it is the end of that period. Free accounts have a one-time grant and no billing period, so the key is absent there; usage.period then covers the calendar month.

account.email_delivery reports whether Kawaa can currently email the account address. deliverable is always present; when it is false the object also carries reason (for example hard_bounce), since (ISO 8601) and a provider detail string — a suppressed address receives no job, credit or security emails until it is fixed in the dashboard:

email_delivery when undeliverable

"email_delivery": {
  "deliverable": false,
  "reason": "hard_bounce",
  "since": "2026-08-06T16:31:11.000Z",
  "detail": "OnAccountSuppressionList"
}

List API keys

GET/v1/api-keys

List all API keys associated with your account.

Response

{
  "success": true,
  "data": {
    "api_keys": [
      {
        "key_id": "key_1a2b3c4d5e6f7a8b",
        "name": "Production",
        "status": "active",
        "created_at": "2025-06-15T10:00:00Z",
        "last_used_at": "2026-02-03T14:30:00Z",
        "key_preview": "ev_****cdEf"
      },
      {
        "key_id": "key_9f8e7d6c5b4a3f2e",
        "name": "Development",
        "status": "active",
        "created_at": "2025-07-01T12:00:00Z",
        "last_used_at": null,
        "key_preview": "ev_****Xy12"
      }
    ]
  }
}

Create API key

POST/v1/api-keys

Request body

Parameter	Type	Required	Description
`name`	string	Required	A name to identify this key
`scopes`	string[]	Optional	Limit the key to these permissions. Omit for a key that can do everything your account can — omit it, don't send `null`. `GET /v1/api-keys` lists every scope in `available_scopes`, and a suggested set for AI agents in `recommended_agent_scopes`.

Important: The full API key is only shown once in the response. Store it securely.

API keys use your account's access and plan limits and do not expire automatically. Creation accepts name and an optional scopes array; other fields, including permissions, expires_at and rate_limit, return HTTP 400. So do scopes: null and scopes: [] — the first because omitting the field is how you ask for an unrestricted key and we will not guess, the second because it would issue a key that can call nothing. Revoke keys you no longer need.

201 Created

HTTP/1.1 201 Created

{
  "success": true,
  "data": {
    "api_key": {
      "key": "ev_aB3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xY",
      "key_id": "key_2b3c4d5e6f7a8b9c",
      "name": "Mobile App",
      "created_at": "2026-02-03T15:00:00Z",
      "scopes": null,
      "warning": "Save this API key now. You will not be able to see it again."
    }
  }
}

Revoke API key

DELETE/v1/api-keys/{key_id}

Permanently revoke an API key. This action cannot be undone.

Response

{
  "success": true,
  "data": {
    "message": "API key revoked successfully",
    "key_id": "key_2b3c4d5e6f7a8b9c"
  }
}

Credit balance

Monitor your credit usage to ensure uninterrupted service.

Credit consumption

1 credit:: Single email verification (cache miss)
0.5 credits:: Cached result (within 24 hours)
1 credit:: Each email in batch verification
5 credits:: A blacklist or DMARC check — whether run on its own, triggered on an existing monitor, or as the initial check that runs when you add a monitor. Scheduled re-checks on a monitor you already own are included.
10 credits:: Deliverability check, domain search
Free:: Job status checks, account info