# Reading verification results

Source: https://docs.rocketverifier.com/results

> Branch on status, which always holds one of four values. Read sub_status for the precise reason, score for a calibrated 0 to 100 chance of delivery, catch_all_verdict for accept-all domains and did_you_mean for typos. Deliverable, undeliverable and risky results cost 1 credit; unknown results are free and carry a retry_after hint.

Every result answers three questions: can I send to this address (`status`), why (`sub_status`), and how confident is the verdict (`score`). The rest of the fields help you segment lists, explain decisions to users and debug edge cases.

## What a result contains

A result is one JSON object with a fixed set of fields. These are the ones that drive decisions:

| Field | Type | Use it for |
| --- | --- | --- |
| `status` | string | The decision. Always `deliverable`, `undeliverable`, `risky` or `unknown`. |
| `sub_status` | string | The precise reason, one of 25 values. `none` when there is nothing to add. |
| `score` | integer 0 to 100 | Calibrated chance the address delivers. Use it to rank and threshold. |
| `deliverability_tier` | string | The score band: `excellent`, `good`, `fair`, `poor` or `unknown`. |
| `catch_all_verdict` | string or null | `send_safe`, `send_with_caution` or `avoid` on accept-all domains. |
| `did_you_mean` | string or null | A corrected address when the input looks like a typo. |
| `retry_after` | integer or null | Seconds to wait before retrying an `unknown` result. |
| `verdict_source` | string | Where the verdict came from: `smtp`, `dns`, `syntax`, `list`, `precheck` or `cache`. |
| `verified_at` | ISO 8601 | When the verdict was produced. |

The full field list, including `domain`, `account`, `smtp_provider`, `gateway` and `evidence`, is in the [verify reference](https://docs.rocketverifier.com/api/verify#response).

## Status

`status` is the only field you need to branch on. It always holds one of four values, and the action for each is the same in every product.

| status | What to do | Meaning | Cost |
| --- | --- | --- | --- |
| `deliverable` | Send | The mail server explicitly accepted the mailbox. | 1 credit |
| `undeliverable` | Remove | The address will bounce: the mailbox, domain or syntax is invalid, or the address is disposable. | 1 credit |
| `risky` | Send with care | The address accepts mail but carries a risk: catch-all domain, role address, full mailbox, trap or abuse signals. | 1 credit |
| `unknown` | Retry later | The mail server gave no conclusive answer. Retry after retry_after seconds. | Free |

Only an explicit answer from the mail server produces `deliverable` or `undeliverable`. When a server blocks the check, greylists it or times out, the result is `unknown` and free, instead of a guess.

Catch-all addresses are `risky` under the current [result version](https://docs.rocketverifier.com/versioning), `2026-11-01`. Keys created before November 2026 use `2025-01-01`, which reports them as `unknown`. Send the `RocketVerifier-Version: 2026-11-01` header to get the current mapping on any key.

## Sub status

`sub_status` names the single most important reason behind the status, so two addresses with the same status can be treated differently. The table lists all 25 values with the status each one belongs to and its cost.

| sub_status | status | Meaning | Cost |
| --- | --- | --- | --- |
| `none` | deliverable | Mailbox confirmed, no other flags. | 1 credit |
| `alias` | deliverable | Mailbox confirmed. The address is sub-addressed (name+tag@). | 1 credit |
| `forwarder` | deliverable | Mailbox confirmed on a forwarding service that relays to another inbox. | 1 credit |
| `mailbox_not_found` | undeliverable | The mail server rejected the mailbox, for example 5.1.1 user unknown. | 1 credit |
| `account_disabled` | undeliverable | The mailbox exists but is disabled. | 1 credit |
| `does_not_accept_mail` | undeliverable | The domain does not accept mail: null MX, no mail route, or a 521 reply. | 1 credit |
| `invalid_syntax` | undeliverable | The address is not syntactically valid. | 1 credit |
| `invalid_domain` | undeliverable | The domain does not exist (NXDOMAIN). | 1 credit |
| `disposable` | undeliverable | A disposable or temporary inbox provider. | 1 credit |
| `catch_all` | risky | The domain accepts every address. Read catch_all_verdict for a per-address recommendation. | 1 credit |
| `role_based` | risky | A role address such as info@ or support@ that reaches a team, not a person. | 1 credit |
| `mailbox_full` | risky | The mailbox exists but is over quota. | 1 credit |
| `possible_trap` | risky | Matches spam trap signals. | 1 credit |
| `toxic` | risky | The address is linked to abuse, complaints or bot signups. | 1 credit |
| `do_not_mail` | risky | A known complainer, or an address on your own suppression list. | 1 credit, free for your suppression list |
| `accepts_then_bounces` | risky | The server accepts at SMTP time but this mailbox is known to bounce later. | 1 credit |
| `privacy_relay` | risky | A privacy relay address (SimpleLogin or addy.io) that forwards to a hidden inbox. | 1 credit |
| `parked_domain` | risky | The domain is parked and unlikely to have a monitored inbox. | 1 credit |
| `possible_typo` | risky | Likely a typo. did_you_mean holds the suggested address. Reported as unknown, and free, when the mailbox could not be checked. | 1 credit |
| `dns_error` | unknown | DNS lookup failed temporarily (SERVFAIL or timeout). | Free |
| `greylisted` | unknown | The mail server asked us to retry later. | Free |
| `blocked` | unknown | The mail server refused the check: policy, blocklist or reputation rejection such as 5.7.x. | Free |
| `smtp_timeout` | unknown | The SMTP conversation timed out. | Free |
| `no_connect` | unknown | Could not connect to the mail server. | Free |
| `smtp_unavailable` | unknown | No conclusive SMTP answer for another reason. | Free |

When several reasons apply, the strongest wins: suppression first, then syntax, disposable domains, DNS failures, mailbox rejections, transient SMTP failures and finally the risk signals (traps, complaints, typos, catch-all, role). A role address on a catch-all domain is reported as `catch_all`, for example.

The older `reason` field is still returned for existing integrations. It is derived from `sub_status`, so the two always agree, but `sub_status` is more precise. New code should read `sub_status`.

### Transient unknowns and their retry hints

Six `unknown` sub statuses are temporary, and each has a default `retry_after`:

| `sub_status` | Default `retry_after` | What happened |
| --- | --- | --- |
| `dns_error` | 60 seconds | DNS lookup failed temporarily. |
| `smtp_timeout` | 60 seconds | The mail server did not answer in time. |
| `smtp_unavailable` | 120 seconds | No conclusive SMTP answer for another reason. |
| `greylisted` | 300 seconds | The server asked for a retry later. When it names a wait, that value is used (60 to 1,800 seconds). |
| `no_connect` | 300 seconds | The mail server refused the connection. |
| `blocked` | 900 seconds | The server refused the check by policy or reputation (for example 5.7.x). |

Bulk jobs retry greylisted addresses for you, up to three times about ten minutes apart, before they report a final result.

## Score and deliverability tier

`score` is a calibrated probability from 0 to 100: a score of 80 means about 80 percent of addresses with the same signals delivered. It is fitted on mailboxes with a known answer and on real bounce outcomes from connected sending platforms.

For every address that reaches the mailbox check, the score agrees with the status:

- **Rejected mailboxes** (`mailbox_not_found`, `account_disabled`) are capped at 10.
- **Unknown** results are capped at 60.
- **Toxic** addresses are capped at 40.

Results decided before the mailbox check (bad syntax, a disposable provider, a domain that does not exist) carry a fixed score that reflects confidence in that verdict. Branch on `status` first and use `score` to rank addresses within a status, never on its own.

`deliverability_tier` is a label for the score band, handy for spreadsheets and CRM fields:

| Tier | Score |
| --- | --- |
| `excellent` | 85 to 100 |
| `good` | 70 to 84 |
| `fair` | 45 to 69 |
| `poor` | 20 to 44 |
| `unknown` | below 20 |

Results decided by syntax, suppression, disposable or DNS checks report `deliverability_tier: "unknown"`. The domain's SPF, DKIM and DMARC posture is reported separately in `authentication_score`.

## Catch-all verdict

`catch_all_verdict` is set whenever the domain accepts mail for every address, and `null` otherwise. It is a per-address recommendation, not a domain flag.

| catch_all_verdict | Meaning |
| --- | --- |
| `send_safe` | Resolution score 65 or higher: strong signals this mailbox is real and active. |
| `send_with_caution` | Resolution score 35 to 64, or too little evidence to decide. Send to engaged segments or warm the address first. |
| `avoid` | Resolution score below 35: signals point to a mailbox that does not exist. |

The `catch_all` object adds the 0 to 100 resolution `score`, the `method` (`pattern` or `heuristic`) and up to five plain-language `reasons`. The [catch-all guide](https://docs.rocketverifier.com/catch-all) explains how the verdict is reached and how to act on each value.

## Typo suggestions

`did_you_mean` holds a full corrected address when the domain looks like a typo of a known mail provider, for example `maya@gmail.com` for `maya@gmial.com`. It is never set on a `deliverable` result.

- When the typo domain does not exist or receive mail, the result is `undeliverable` with `sub_status` `invalid_domain` or `does_not_accept_mail`, and `did_you_mean` carries the fix.
- When the typo domain does receive mail (a known typo domain), the result is `risky` with `sub_status` `possible_typo`. If the mailbox could not be checked, it is `unknown` with `possible_typo`, and free.

Show the suggestion and let the person confirm it. Never rewrite the address silently.

## Retry unknown results

An `unknown` result is free, so retrying it costs nothing until the server gives a real answer. Wait at least `retry_after` seconds, then verify again.

- **Signup forms:** accept the address, then re-check it in the background before the first important email.
- **Lists:** keep unknown rows in a separate segment and re-verify them in a later job. The [list cleaning guide](https://docs.rocketverifier.com/guides/list-cleaning) shows the full loop.
- **`blocked`:** the mail server rejects verification probes by policy. Retrying later often succeeds; repeated `blocked` results on one domain mean that server never answers probes.

## What is charged

Each verification costs 1 credit, except where it cost us no verification work or gave no answer.

| Result | Cost |
| --- | --- |
| `deliverable`, `undeliverable`, `risky` | 1 credit |
| Catch-all, in either result version | 1 credit |
| `unknown` (every transient sub status, `possible_typo` reported as unknown) | Free |
| Address on your own suppression list (`do_not_mail`) | Free |
| Sandbox addresses at `@sandbox.rocketverifier.com` | Free |
| Retry with the same `Idempotency-Key` within 24 hours | Free (the stored result is returned) |
| Duplicate addresses inside one bulk job | Free (each unique address is charged once) |

Bulk jobs are charged 1 credit per unique address up front, and unknown results are refunded when the job completes.

## Decide by use case

The right action depends on where the address came from. At signup, a person is typing and can fix a mistake right now. In a list, nobody is there to ask, so you protect your sender reputation.

| Result | Signup form | List cleaning |
| --- | --- | --- |
| `deliverable` | Accept | Keep |
| `undeliverable` with `did_you_mean` | Block and show the suggestion | Remove, or fix it if you can confirm with the contact |
| `undeliverable` (any other) | Block: "This address can't receive email" | Remove |
| `disposable` | Block: ask for a permanent address | Remove |
| `risky` + `role_based` | Accept | Keep for B2B and transactional mail |
| `risky` + `catch_all` | Accept unless `catch_all_verdict` is `avoid` | Keep `send_safe`, segment `send_with_caution`, remove `avoid` |
| `risky` + `possible_typo` | Warn and show `did_you_mean` | Review |
| `risky` + `mailbox_full` | Accept | Suppress for now, re-verify later |
| `risky` + `possible_trap`, `toxic`, `do_not_mail` | Block | Remove |
| `risky` + `accepts_then_bounces`, `parked_domain` | Warn | Remove |
| `risky` + `privacy_relay` | Accept | Keep |
| `unknown` | Accept and re-check in the background | Hold in a segment and re-verify |

## Branch on results in code

This function turns a result into one of three actions. It reads the raw API fields, so it works with any HTTP client. The SDKs expose the same fields in their own casing (`subStatus` and `didYouMean` in Node.js).

Node.js:

```js
const BLOCK = new Set(["possible_trap", "toxic", "do_not_mail", "disposable"]);
const WARN = new Set(["possible_typo", "accepts_then_bounces", "parked_domain"]);

export async function verify(email) {
  const res = await fetch("https://api.rocketverifier.com/v1/verify", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ROCKETVERIFIER_API_KEY}`,
      "Content-Type": "application/json",
      "RocketVerifier-Version": "2026-11-01",
    },
    body: JSON.stringify({ email }),
  });
  if (!res.ok) throw new Error(`RocketVerifier ${res.status}`);
  return res.json();
}

export function decide(r) {
  if (r.status === "deliverable") return { action: "accept" };
  if (r.status === "unknown") return { action: "accept", retryInSeconds: r.retry_after ?? 300 };
  if (r.status === "undeliverable" || BLOCK.has(r.sub_status)) {
    return { action: "block", suggestion: r.did_you_mean };
  }
  if (r.sub_status === "catch_all" && r.catch_all_verdict === "avoid") return { action: "block" };
  if (WARN.has(r.sub_status)) return { action: "warn", suggestion: r.did_you_mean };
  return { action: "accept", flag: r.sub_status }; // role_based, catch_all, mailbox_full, privacy_relay
}

const result = await verify("maya@northwind.io");
console.log(decide(result));
```

Python:

```python
import os
import requests

BLOCK = {"possible_trap", "toxic", "do_not_mail", "disposable"}
WARN = {"possible_typo", "accepts_then_bounces", "parked_domain"}

def verify(email: str) -> dict:
    res = requests.post(
        "https://api.rocketverifier.com/v1/verify",
        headers={
            "Authorization": f"Bearer {os.environ['ROCKETVERIFIER_API_KEY']}",
            "RocketVerifier-Version": "2026-11-01",
        },
        json={"email": email},
        timeout=35,
    )
    res.raise_for_status()
    return res.json()

def decide(r: dict) -> dict:
    if r["status"] == "deliverable":
        return {"action": "accept"}
    if r["status"] == "unknown":
        return {"action": "accept", "retry_in_seconds": r.get("retry_after") or 300}
    if r["status"] == "undeliverable" or r["sub_status"] in BLOCK:
        return {"action": "block", "suggestion": r.get("did_you_mean")}
    if r["sub_status"] == "catch_all" and r.get("catch_all_verdict") == "avoid":
        return {"action": "block"}
    if r["sub_status"] in WARN:
        return {"action": "warn", "suggestion": r.get("did_you_mean")}
    return {"action": "accept", "flag": r["sub_status"]}  # role_based, catch_all, mailbox_full, privacy_relay

print(decide(verify("maya@northwind.io")))
```

## Results in bulk jobs

Bulk job rows use the same vocabulary. [`GET /v1/jobs/{id}/results`](https://docs.rocketverifier.com/api/batch) returns `status`, `sub_status`, `confidence_score` (the score), `is_catch_all` and `verified_at` for each address, and honours the `RocketVerifier-Version` header. Downloads add `did_you_mean`, `catch_all_verdict`, `catch_all_score` and the other detail columns, and can be filtered to one segment such as `deliverable` or `send_safe`.

## Next steps

- [Catch-all domains](https://docs.rocketverifier.com/catch-all)
How the catch-all verdict is reached and what to send to.
- [Result versions](https://docs.rocketverifier.com/versioning)
Pick how catch-all results map onto status with one header.
- [Verify at signup](https://docs.rocketverifier.com/guides/signup-verification)
Block bad addresses on your forms with a server-side check or RocketShield.
- [Clean a list](https://docs.rocketverifier.com/guides/list-cleaning)
Upload, preview for free, verify and download clean segments.

## Frequently asked questions

### Am I charged for unknown results?

No. An unknown result means the mail server gave no conclusive answer, so it costs nothing. Retry after the number of seconds in retry_after. Addresses on your own suppression list are also free.

### Is a risky address safe to send to?

It accepts mail but carries a specific risk, named in sub_status. Role addresses and catch-all addresses with a send_safe verdict are usually fine for opted-in mail. Drop possible_trap, toxic and do_not_mail addresses from every send.

### What does a score of 80 mean?

For addresses that reach the mailbox check, the score is a calibrated probability. A score of 80 means about 80 percent of addresses with the same signals delivered. It is capped at 10 for rejected mailboxes and 60 for unknown results. Branch on status first and use the score to rank within a status.

### Why is verified_at earlier than my request?

Results are cached for 6 hours (5 minutes for transient unknowns), so a repeat check returns the cached verdict in milliseconds. verified_at shows when the verdict was produced and verdict_source is cache.

### Should I auto-correct addresses with a did_you_mean suggestion?

No. Show the suggestion to the person and let them confirm it. did_you_mean holds a full corrected address, for example maya@gmail.com for maya@gmial.com.
