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