Understand results
Reading verification results
In short
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.
On this page
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.
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.
deliverable1 creditSend
The mail server explicitly accepted the mailbox.
undeliverable1 creditRemove
The address will bounce: the mailbox, domain or syntax is invalid, or the address is disposable.
risky1 creditSend with care
The address accepts mail but carries a risk: catch-all domain, role address, full mailbox, trap or abuse signals.
unknownFreeRetry later
The mail server gave no conclusive answer. Retry after retry_after seconds.
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, 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 | What it means |
|---|---|
| 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 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
undeliverablewithsub_statusinvalid_domainordoes_not_accept_mail, anddid_you_meancarries the fix. - When the typo domain does receive mail (a known typo domain), the result is
riskywithsub_statuspossible_typo. If the mailbox could not be checked, it isunknownwithpossible_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 shows the full loop.
blocked: the mail server rejects verification probes by policy. Retrying later often succeeds; repeatedblockedresults 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).
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));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 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#
How the catch-all verdict is reached and what to send to.
Result versionsPick how catch-all results map onto status with one header.
Verify at signupBlock bad addresses on your forms with a server-side check or RocketShield.
Clean a listUpload, 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.
Updated 11 November 2026Suggest an edit