Skip to content
RocketVerifierDOCS

Understand results

Result versions

In short

The RocketVerifier-Version header picks how results map onto status. 2026-11-01, the current version, reports catch-all addresses as risky; 2025-01-01 reports them as unknown. Everything else is identical. API keys created from November 2026 default to 2026-11-01, and a valid header always wins.

On this page

The public status vocabulary (deliverable, undeliverable, risky, unknown) is stable. How one kind of result maps onto it changed once, in November 2026, and the result version lets each integration choose the mapping it was built for.

What differs between versions#

Only catch-all addresses change. Every other field, value and charge is the same in both versions.

Result2025-01-01 (legacy)2026-11-01 (current)
Mailbox confirmeddeliverabledeliverable
Mailbox rejected, bad syntax or domain, disposableundeliverableundeliverable
Risk signal (role, full mailbox, trap, toxic, typo and others)riskyrisky
Catch-all domainunknownrisky
No conclusive answerunknownunknown

Under 2026-11-01, unknown always means "no answer yet, free, retry later". Under 2025-01-01, unknown mixes those free results with catch-all addresses, which are charged and carry a catch-all verdict. The current version keeps the two apart, so status alone tells you whether a retry makes sense.

Pick a version with the header#

Send RocketVerifier-Version with 2026-11-01 or 2025-01-01 on any request.

curl -X POST https://api.rocketverifier.com/v1/verify \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "RocketVerifier-Version: 2026-11-01" \
  -d '{"email": "maya.patel@lakeside-dental.com"}'

The header applies to every endpoint that returns a public status:

  • POST /v1/verify
  • GET /v1/jobs/{id}/results
  • GET /v1/jobs/{id}/download, including the filter=risky and filter=unknown segments
  • The email.verified webhook payload of a real-time check, which carries the status that request returned

Defaults when no header is sent#

The effective version is chosen in this order: a valid header, then the credential's own version, then 2025-01-01.

CredentialDefault version
API key created from November 20262026-11-01
API key created before November 20262025-01-01
Organization API key2025-01-01
OAuth access token (rv_at_)2025-01-01
Dashboard2026-11-01, always

A key's version is fixed when the key is created. To move a key to the current mapping, send the header, or create a new key in the dashboard and swap it in.

Migrate to 2026-11-01#

Migration takes one header and one review of code that handles unknown.

  1. Find code that treats unknown as catch-all

    Search for places that read status === "unknown" and then check domain.acceptAll, reason === "catch_all" or catch_all_verdict. Under the current version those addresses arrive as risky with sub_status: "catch_all".

  2. Move catch-all handling to the risky branch

    Read catch_all_verdict inside your risky branch: send send_safe, segment send_with_caution, drop avoid. Your unknown branch now only ever sees free results to retry after retry_after seconds.

  3. Send the header everywhere

    Add RocketVerifier-Version: 2026-11-01 to every request, including job result reads and downloads, so live checks and stored results use the same mapping.

  4. Check dashboards and reports

    Counts by status shift: catch-all addresses move from unknown to risky. Job counters such as catch_all_count in GET /v1/jobs/{id} and the job.completed webhook are reported separately and do not change.

Pinning the header is also the safest way to keep an integration stable: your results stay on the version you tested against, whatever key runs them.

Next steps#

Frequently asked questions

Which version should I use?

2026-11-01. It reports catch-all addresses as risky, which keeps unknown for results that are free and worth retrying. New integrations should send the header on every request.

Does the version change what I am charged?

No. Catch-all results cost 1 credit in both versions, and unknown results are free in both. The version changes only the status label of catch-all addresses.

What happens if I send an unsupported version?

The header is ignored and the key's version applies, or 2025-01-01 when the key has none. Check the value for typos if results do not change.

Which version does the dashboard use?

The dashboard always shows results with the current version, 2026-11-01.

Updated 11 November 2026Suggest an edit