Skip to content
Docs Single verification

Single verification

POST or GET /verify: request shapes and every response field.

Two equivalent endpoints verify one address:

request.sh
# POST with JSON body
curl -X POST "https://api.kavik.email/api/v1/verify" \
  -H "X-API-Key: eva_your_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@acmecorp.com"}'

# GET with query parameter
curl "https://api.kavik.email/api/v1/verify?email=jane@acmecorp.com" \
  -H "X-API-Key: eva_your_key"

Repeat lookups for the same address may be served from a short-lived cache for speed; each call counts toward your usage once per call.

With a test key, use the test addresses in the sandbox, such as safe@example.com. Anything else is refused with LIVE_KEY_REQUIRED.

Response fields

Field Type Meaning
email string The address as submitted
score integer 0-100 Composite deliverability score
risk enum safe (70-100), risky (40-69), catchall (40-69: the domain accepts every address, so the mailbox itself is unconfirmed; never billed), invalid (0-39), unknown (no definitive answer; never billed)
syntax_valid boolean RFC-correct address syntax
mx_found boolean The domain publishes MX records. false with smtp_check: undeliverable means no mail server answers anywhere RFC 5321 falls back to
smtp_check enum deliverable, undeliverable, risky, unknown
is_disposable boolean Known disposable provider
is_role_account boolean Role address (info@, sales@, …)
is_catch_all boolean Domain accepts every local part; the address gets the catchall verdict and the score orders it inside a 40-69 band unless the mailbox was actually refused
is_free_provider boolean Free mailbox provider (Gmail, Outlook, …)
spam_trap_risk enum low, medium, high
suggested_correction string or null Did-you-mean suggestion when a domain typo is detected. Suggestion only: we never verify the corrected address on your behalf
mx_records array The domain’s MX hosts
is_security_gateway boolean Mail routes through Mimecast, Proofpoint, etc.
security_gateway string Gateway name or empty
has_gravatar boolean A Gravatar profile exists for the address
gravatar_url string Present when has_gravatar is true
livemode boolean true for a live key, false for a test key

Batch verification

For up to 100 addresses in one call, use POST /api/v1/verify/batch with {"emails": ["a@x.com", "b@y.com"]}. Duplicates are removed before anything is charged. The response is {"total", "results", "livemode"}, and each result carries livemode too.

A batch answers within about 80 seconds. An address whose check is still running then, because its mail server is slow to answer or its provider takes checks a few at a time, comes back in a checking list instead of results. It is not billed in that call, and its check keeps running. Call the endpoint again with those addresses to get their results: the second call waits for the running checks instead of starting new ones. total counts the results, and the X-Checking-Count header gives the number under checking. Match results to your list by email, not by position.

Account

GET /api/v1/account returns the plan and checks left for the key you call it with. A live key and a test key both work.

account.sh
curl "https://api.kavik.email/api/v1/account" \
  -H "X-API-Key: eva_your_key"
{}account.json
{
  "data": {
    "plan": "starter",
    "livemode": true,
    "period_start": "2026-11-01",
    "period_end": "2026-12-01",
    "allowance_renews": true,
    "monthly_limit": 20000,
    "total_used": 1250,
    "remaining": 18750,
    "pool_credits": 0,
    "daily_used": 0,
    "free_allowance_held": false,
    "checks_per_minute": 20
  }
}
Field Meaning
plan The plan of the account the key is charged to
livemode true for a live key, false for a test key
period_start, period_end The current period. period_end is empty on the Free plan
allowance_renews false on the Free plan, whose 300 checks do not renew
monthly_limit, total_used The period’s allowance and how much of it is used
remaining Plan checks left plus credits. 0 for a Free account without credits, because its 300 checks are for the dashboard
pool_credits Credit-pack checks held
daily_limit, daily_used The Free plan’s daily cap, when one applies, and today’s use
free_allowance_held The free allowance is withheld until a plan or a credit pack is bought
checks_per_minute The account’s per-minute check budget
sandbox Test keys only: requests_per_minute, max_bulk_rows, max_running_jobs, max_jobs_per_hour

The answer is for the pool the calling key is charged to. The call is never charged, and it is limited to 60 requests a minute per account. Its X-RateLimit-Limit: 60 is the limit of this endpoint, not checks_per_minute.