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.
Authorization: Bearer
Bearer token API key on every request. Revocable, no soft-rotate.
/api/v1/verify/single
Synchronous. ~150ms cached, 1 to 3s fresh.
/api/v1/verify/bulk
Async CSV up to 5M rows. Optional callback URL.
Rate limits
30/min single · 10/hr bulk · 3/day public.
HTTP + JSON detail
401 · 402 · 429 · 500. Retry-After on rate limit.
Missing today
OpenAPI · SDKs · webhook signatures · status page.
Authentication
Every request takes an API key. Create one from Settings → API keys in the dashboard. Keys start with the kb__ prefix (double underscore). Keys are revocable any time; no soft-rotate window, once revoked they stop working immediately.
Pass the key in either of two headers (whichever your HTTP client makes easier):
# Both headers work — pick either:
Authorization: Bearer kb__<your_key>
# or
X-API-Key: kb__<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/api/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",
"is_valid": true,
"status": "valid",
"sub_status": "valid_mailbox",
"reason": null,
"score": 95,
"syntax_valid": true,
"domain_exists": true,
"smtp_valid": true,
"is_disposable": false,
"is_role_based": false,
"is_free_email": false,
"is_catch_all": false,
"disposable_flag": "no",
"role_flag": "no",
"free_flag": "no",
"catch_all_flag": "no",
"mx_records": ["aspmx.l.google.com"],
"smtp_provider": "Google Workspace",
"did_you_mean": null,
"retry_after_seconds": 0,
"verified_at": "2026-10-09T12:50:27.776395Z",
"credits_used": 1,
"from_cache": false
}status is lowercase, one of valid / risky / invalid / unknown. The 0 to 100 score is the deliverability confidence; buckets are not interchangeable, the score gives you a continuous signal under each bucket.
sub_status is a granular code alongside status, e.g. risky_catch_all_google, risky_greylisted, invalid_mailbox_not_found. Use it to bucket contacts by the reason behind the verdict, not just the top-level 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/api/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 retryWhat 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.