Skip to content
RocketVerifierDOCS

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:

FieldTypeUse it for
statusstringThe decision. Always deliverable, undeliverable, risky or unknown.
sub_statusstringThe precise reason, one of 25 values. none when there is nothing to add.
scoreinteger 0 to 100Calibrated chance the address delivers. Use it to rank and threshold.
deliverability_tierstringThe score band: excellent, good, fair, poor or unknown.
catch_all_verdictstring or nullsend_safe, send_with_caution or avoid on accept-all domains.
did_you_meanstring or nullA corrected address when the input looks like a typo.
retry_afterinteger or nullSeconds to wait before retrying an unknown result.
verdict_sourcestringWhere the verdict came from: smtp, dns, syntax, list, precheck or cache.
verified_atISO 8601When 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 credit

Send

The mail server explicitly accepted the mailbox.

undeliverable1 credit

Remove

The address will bounce: the mailbox, domain or syntax is invalid, or the address is disposable.

risky1 credit

Send with care

The address accepts mail but carries a risk: catch-all domain, role address, full mailbox, trap or abuse signals.

unknownFree

Retry 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_statusStatusMeaningCost
nonedeliverableMailbox confirmed, no other flags.1 credit
aliasdeliverableMailbox confirmed. The address is sub-addressed (name+tag@).1 credit
forwarderdeliverableMailbox confirmed on a forwarding service that relays to another inbox.1 credit
mailbox_not_foundundeliverableThe mail server rejected the mailbox, for example 5.1.1 user unknown.1 credit
account_disabledundeliverableThe mailbox exists but is disabled.1 credit
does_not_accept_mailundeliverableThe domain does not accept mail: null MX, no mail route, or a 521 reply.1 credit
invalid_syntaxundeliverableThe address is not syntactically valid.1 credit
invalid_domainundeliverableThe domain does not exist (NXDOMAIN).1 credit
disposableundeliverableA disposable or temporary inbox provider.1 credit
catch_allriskyThe domain accepts every address. Read catch_all_verdict for a per-address recommendation.1 credit
role_basedriskyA role address such as info@ or support@ that reaches a team, not a person.1 credit
mailbox_fullriskyThe mailbox exists but is over quota.1 credit
possible_trapriskyMatches spam trap signals.1 credit
toxicriskyThe address is linked to abuse, complaints or bot signups.1 credit
do_not_mailriskyA known complainer, or an address on your own suppression list.1 credit, free for your suppression list
accepts_then_bouncesriskyThe server accepts at SMTP time but this mailbox is known to bounce later.1 credit
privacy_relayriskyA privacy relay address (SimpleLogin or addy.io) that forwards to a hidden inbox.1 credit
parked_domainriskyThe domain is parked and unlikely to have a monitored inbox.1 credit
possible_typoriskyLikely a typo. did_you_mean holds the suggested address. Reported as unknown, and free, when the mailbox could not be checked.1 credit
dns_errorunknownDNS lookup failed temporarily (SERVFAIL or timeout).Free
greylistedunknownThe mail server asked us to retry later.Free
blockedunknownThe mail server refused the check: policy, blocklist or reputation rejection such as 5.7.x.Free
smtp_timeoutunknownThe SMTP conversation timed out.Free
no_connectunknownCould not connect to the mail server.Free
smtp_unavailableunknownNo 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_statusDefault retry_afterWhat happened
dns_error60 secondsDNS lookup failed temporarily.
smtp_timeout60 secondsThe mail server did not answer in time.
smtp_unavailable120 secondsNo conclusive SMTP answer for another reason.
greylisted300 secondsThe server asked for a retry later. When it names a wait, that value is used (60 to 1,800 seconds).
no_connect300 secondsThe mail server refused the connection.
blocked900 secondsThe 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:

TierScore
excellent85 to 100
good70 to 84
fair45 to 69
poor20 to 44
unknownbelow 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_verdictWhat it means
send_safeResolution score 65 or higher: strong signals this mailbox is real and active.
send_with_cautionResolution score 35 to 64, or too little evidence to decide. Send to engaged segments or warm the address first.
avoidResolution 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 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 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.

ResultCost
deliverable, undeliverable, risky1 credit
Catch-all, in either result version1 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.comFree
Retry with the same Idempotency-Key within 24 hoursFree (the stored result is returned)
Duplicate addresses inside one bulk jobFree (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.

ResultSignup formList cleaning
deliverableAcceptKeep
undeliverable with did_you_meanBlock and show the suggestionRemove, or fix it if you can confirm with the contact
undeliverable (any other)Block: "This address can't receive email"Remove
disposableBlock: ask for a permanent addressRemove
risky + role_basedAcceptKeep for B2B and transactional mail
risky + catch_allAccept unless catch_all_verdict is avoidKeep send_safe, segment send_with_caution, remove avoid
risky + possible_typoWarn and show did_you_meanReview
risky + mailbox_fullAcceptSuppress for now, re-verify later
risky + possible_trap, toxic, do_not_mailBlockRemove
risky + accepts_then_bounces, parked_domainWarnRemove
risky + privacy_relayAcceptKeep
unknownAccept and re-check in the backgroundHold 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));

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#

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