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.

The four verdicts

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.

Reason codes

"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.

valid

reason_code Mode Meaning What to do
mailbox_exists mailbox Recipient accepted and a random control address rejected Send

invalid

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

risky

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

unknown

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

The rest of the result

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

A sensible default policy

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