Verdicts and reason codes
Every verification answers with a verdict and a reason_code. The verdict is the decision; the reason code is the evidence behind it.
verdict |
Meaning |
What to do |
valid |
The mail server accepts the recipient and rejects a random control address on the same server |
Send. It does not prove the mailbox is read |
invalid |
Unsupported syntax, a domain that cannot receive mail, or an unambiguous "no such recipient" |
Do not send. Remove it or ask for a correction |
risky |
Accept-all server, disposable or legacy domain, forwarding, full or disabled mailbox, or a provider rejection without confirmation |
Decide by reason_code and by how much a bounce costs you |
unknown |
Mailbox not checked (basic), timeout, greylisting, temporary DNS or SMTP failure, probe quota or an ambiguous answer |
Keep it. Retry after retry_at when present |
Never treat unknown as invalid. unknown means "we could not tell", not "it does not exist". In mailbox mode an unknown result is never charged.
Only mailbox mode can return valid. basic mode never contacts the mail server, so a healthy domain gives unknown with mailbox_not_checked.
"Mode" says where the code can appear. New codes may be added without a version change: when you meet one you do not know, fall back on the verdict.
reason_code |
Mode |
Meaning |
What to do |
mailbox_exists |
mailbox |
Recipient accepted and a random control address rejected |
Send |
reason_code |
Mode |
Meaning |
What to do |
syntax_invalid |
both |
Not a valid address in the supported ASCII profile |
Ask for a correction. Never send |
domain_not_found |
both |
The domain does not exist (NXDOMAIN) |
Usually a typo in the domain. Ask for a correction |
domain_null_mx |
both |
The domain declares that it accepts no mail (null MX, RFC 7505) |
Remove |
domain_no_mail_host |
both |
No MX record and no A or AAAA record |
Remove |
mailbox_not_found |
mailbox |
The server says the recipient does not exist |
Remove. Sending would bounce |
reason_code |
Mode |
Meaning |
What to do |
disposable_domain |
both |
The domain is on the disposable-email list |
Reject at sign-up or exclude from campaigns, by your policy |
legacy_domain |
both |
Domain of a discontinued provider |
Ask for a current address. Do not rely on it |
mailbox_disabled |
mailbox |
The server says the mailbox is disabled |
Suppress. Check again later if the contact matters |
mailbox_full |
mailbox |
The server says the mailbox is full |
A send would probably bounce. Check again later |
mailbox_forwarded |
mailbox |
The server announces forwarding (SMTP 251) |
Usually deliverable. The final mailbox is not verified |
provider_directory_rejected |
mailbox |
Provider directory rejection (Microsoft 365) without confirmation |
Treat as probably missing. Keep it out of bulk sends |
catch_all |
mailbox |
The server also accepts a random recipient |
The mailbox cannot be confirmed. Send only if you have another signal, such as recent activity |
reason_code |
Mode |
Meaning |
What to do |
mailbox_not_checked |
basic |
The domain can receive mail and the mailbox was not probed |
Normal answer in basic. Use mailbox mode if you need certainty |
address_unsupported |
both |
Internationalised (non-ASCII) address, not checked |
Do not reject it. Verify it by your own means |
dns_temporary |
both |
DNS failed temporarily. Not charged |
Retry later |
catch_all_unresolved |
mailbox |
Recipient accepted, but the catch-all control was inconclusive |
Retry later. Until then treat it like catch_all |
rejection_unconfirmed |
mailbox |
Rejected, but a known-good control address was rejected too |
The rejection proves nothing. Retry later |
probe_rate_limited |
mailbox |
Our hourly probe quota for that domain or server is exhausted |
Retry after retry_at. Batches do it for you |
probe_blocked |
mailbox |
The server refuses our probe (IP reputation, reverse DNS or sender policy) |
A retry will not help soon. Treat as unverified |
smtp_temporary |
mailbox |
Temporary rejection or greylisting |
Retry after retry_at. Batches do it for you |
smtp_unreachable |
mailbox |
No mail server could be reached |
Retry later |
smtp_tls_failed |
mailbox |
The advertised TLS session could not be verified |
Retry later |
smtp_rejected |
mailbox |
Ambiguous or policy rejection that does not prove the mailbox is missing |
Treat as unverified |
JSON{
"id": "ver_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"object": "verification",
"livemode": true,
"email": "luis@example.org",
"mode": "mailbox",
"verdict": "unknown",
"reason_code": "smtp_temporary",
"reason": "The mail server deferred the check; try again after retry_at.",
"flags": {
"disposable": false,
"free": false,
"catch_all": null
},
"checks": [
{
"name": "syntax",
"status": "ok"
},
{
"name": "dns",
"status": "mx"
},
{
"name": "smtp",
"status": "temporary"
}
],
"mx": [
{
"host": "mail.example.org",
"preference": 5
}
],
"smtp": {
"mx": "mail.example.org",
"code": 451,
"enhanced_code": "4.7.1",
"tls": true
},
"cached": false,
"credits_charged": 0,
"checked_at": "2026-11-17T09:51:10Z",
"retry_at": "2026-11-17T10:06:10Z"
}
| Field |
What it tells you |
reason |
Human-readable explanation of reason_code, in English or Spanish (Accept-Language) |
flags.disposable |
The domain, or a parent domain, is on the disposable list |
flags.free |
Free webmail provider. Informational: it does not change the verdict |
flags.catch_all |
true: the server accepted a random recipient. false: it rejected it. null: not tested or inconclusive |
checks |
The steps that actually ran, in order: syntax, domain lists, dns, smtp, catch_all. Steps that did not run are absent |
mx |
Mail servers of the domain. Empty when DNS was not resolved |
smtp |
What the server answered to RCPT TO: mx, code, enhanced_code, tls. null in basic mode |
cached |
The result comes from a recent check. checked_at is the time of that check |
credits_charged |
0 or 1 credit of the type of mode |
retry_at |
When a temporary result can be verified again. null when a retry makes no sense |
| Situation |
Send to valid |
Send to risky |
Send to unknown |
| Transactional email the user asked for |
Yes |
Yes |
Yes |
| Newsletter to people who signed up |
Yes |
Only mailbox_forwarded and catch_all with recent activity |
After a retry, or in small batches while you watch bounces |
| Cold or old list |
Yes |
No |
No, until a retry gives a verdict |
This is a starting point, not a rule: you know what a bounce costs you.
View this page as Markdown