Check a domain's email authentication
Ten credits for a fresh check; a check of the same domain within 24 hours is served from cache and costs nothing.
Send Idempotency-Key. The DNS work can run for up to 120 seconds while the API stops waiting at about 29, so a client that times out cannot tell whether it paid. With a key, the identical request replays the original result for 30 days and charges nothing; without one, the retry is a new 10-credit check. A key already in flight answers 409, and a receipt that cannot be read answers 503. In both cases retry the identical request rather than starting a fresh one.
A lookup that fails is not a missing record. Only NXDOMAIN or NODATA counts as "no record". An SPF, DKIM, DMARC, MX or PTR lookup that fails (SERVFAIL, REFUSED, a timeout) is named in not_measured, shown as not_measured in authentication, and left out of score rather than scored as missing.
No grade without SPF, DKIM and DMARC. When any of those three is not measured, grade and spam_assessment.spam_likelihood are null and score is a partial figure over what did answer: a letter over the rest would grade records nobody read. A check where only MX or reverse DNS failed is still graded, over the rest. Either way the check is charged, because it measured something; it is refunded (503) only when every lookup timed out or nothing at all could be scored.
Request
- Base URL: https://api.kawaa.com
- URL: https://api.kawaa.com/v1/deliverability/check
- Auth: one of:
- API key in header X-Api-Key
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://api.kawaa.com/oauth/authorize, token URL https://api.kawaa.com/oauth/token, scopes: deliverability:write)
Headers
Makes a charging call safe to retry: a repeat under the same key replays the original outcome instead of buying the work again. The window depends on the route: the receipt behind it expires, and after that the same key is a new paid request. It is 30 days for a deliverability check, at least 30 days for a single find, 24 hours for an activity lookup, and 15 minutes for a bulk find. What a replay returns also differs: a batch replays its JOB, an activity lookup replays its RESULT. A different request under the same key is 409 IDEMPOTENCY_KEY_CONFLICT, before any charge.
How long a key stays safe differs per route, and for the verification routes it depends on the plan. POST /v1/verify, /v1/verify/batch and /v1/verify/file keep their receipts for the job's data-retention period, never less than 30 days, so longer on plans that keep results longer. The job itself is kept only for the plan's data-retention period, which is 7 days on Free: a repeat that arrives after the job's retention period has ended but while its receipt is still live is refused with 410 IDEMPOTENT_JOB_EXPIRED and charged nothing, rather than bought a second time; send a new key to run it again. Once the receipt expires the same key claims a fresh target and creates another paid job. POST /v1/deliverability/check keeps its receipt 30 days. POST /v1/find keeps its receipt at least 30 days and its stored address only for the plan's retention period; a repeat after the address expires but before the receipt does return 410 IDEMPOTENT_JOB_EXPIRED without charging. The activity lookups keep receipts about 24 hours, and POST /v1/find/bulk 15 minutes. Without a key, GET /v1/activity/{email} and GET /v1/activity/domain/{domain} still answer an identical repeat from the same account free for 15 minutes after the lookup that was charged (POST /v1/find/bulk does the same for its content); a key buys a fresh read inside that window. An unkeyed POST /v1/verify that arrives while an identical one from the same account is still being verified (at most 15 minutes after its charge) joins it and is not charged; once that verification has its answer, a repeat is charged as usual. Only a key makes a later retry free.
Retry with the key you have rather than minting a new one. A key is not a refund (it prevents a second charge, it does not undo the first), but it stays good far longer than the shortest advertised retention suggests, and dropping one early is how a retry becomes a second paid job.
The characters are checked after trimming. Surrounding whitespace is trimmed from the header first; the resulting key must be 1-255 printable ASCII characters (0x21-0x7e) other than a comma, with no internal spaces or anything outside that range. Leading and trailing whitespace is accepted and is not part of the key. Because OpenAPI constraints apply to the raw header rather than the post-trim value, this schema deliberately has no minLength, maxLength, or pattern; those constraints would make generated clients reject values the API accepts. Invalid post-trim values get 400 before the route starts. A UUID is the obvious choice. Sending the header twice with different raw values is also a 400. A key may not contain a comma, because a header sent more than once reaches the API joined by commas; a comma is refused with the same 400, before anything is charged. A receipt claimed under a comma-bearing key before 2026-10-03 still replays for its window.
Request body
Example request
{
"domain": "example.com"
}Response
The check. cached and idempotent_replay say whether it was measured now or reused; credits_used is what was actually charged.
Example response
{
"data": {
"checks": {
"dmarc": {
"policy": "none"
}
},
"issues": [
{
"check": "spf"
}
],
"not_measured": {
"dkim": "DKIM lookup failed for 51 of 51 selectors (ESERVFAIL), so DKIM was not measured and is left out of the score."
}
}
}Changes
No recorded changes to this operation across all 1 revision of this API.