API

The endpoints are live. The docs are minimal but honest.

Below is exactly enough to verify your first address from a terminal and the response shape you should expect back. A full OpenAPI reference and first-party SDKs are in progress — until then, this page is what you have.

Authentication

Every request uses a Bearer token API key. Create one from Settings → API keys in the dashboard. Keys are revocable any time; no soft-rotate window — once revoked they stop working immediately.

Authorization: Bearer kb_live_<your_key>

Verify a single address

Synchronous. Returns within ~150ms for cached results, ~1–3s for fresh probes.

curl -X POST https://api.getkillbounce.com/v1/verify/single \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sarah.chen@acme.com",
    "check_smtp": true
  }'

Response shape

{
  "email": "sarah.chen@acme.com",
  "status": "VALID",
  "score": 96,
  "reason": null,
  "syntax_valid": true,
  "domain_exists": true,
  "smtp_valid": true,
  "is_disposable": false,
  "is_role_based": false,
  "is_free_email": false,
  "smtp_provider": "Google Workspace",
  "mx_records": ["aspmx.l.google.com"],
  "from_cache": false,
  "credits_used": 1,
  "verified_at": "2026-06-04T18:00:00Z"
}

status is one of VALID / RISKY / INVALID / UNKNOWN. The 0–100 score is the deliverability confidence — buckets are not interchangeable, the score gives you a continuous signal under each bucket.

Verify a list

Async. Upload up to 5,000,000 addresses per job. Pass a callback_url to get the results POSTed back when the job finishes; results are also downloadable from the dashboard for seven days.

curl -X POST https://api.getkillbounce.com/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@list.csv" \
  -F "callback_url=https://your-app.com/webhooks/verify-complete"

The CSV needs an email column. Any other columns are echoed back in the result file unchanged.

Rate limits

/verify/single: 30 / minute / user.
/verify/bulk: 10 / hour / user. Job processing is concurrent under the hood.
/verify/public: 3 / day / IP, 10 / week (anonymous landing-page widget).

Errors

Standard HTTP status codes. Error bodies are JSON with a single detail field.

401 Unauthorized      — missing or revoked API key
402 Payment Required  — insufficient credits
429 Too Many Requests — rate limit hit; Retry-After header included
500 Internal Error    — credit not deducted; safe to retry

What is missing today

Being explicit so you can budget your integration time honestly:

No publicly hosted OpenAPI explorer (we run it internally; export-on-request via legal@).
No first-party SDKs published yet. Curl + your HTTP client of choice is the stack.
No webhook signature header yet — verify the callback by checking the job-ID and origin IP.
No public status page; subscribe to status@getkillbounce.com for incident notifications.

If any of those is a blocker, email dev@getkillbounce.com with what you need — we will tell you when, or build it sooner.

Get an API key Ask a dev question