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.
| Result | 2025-01-01 (legacy) | 2026-11-01 (current) |
|---|---|---|
| Mailbox confirmed | deliverable | deliverable |
| Mailbox rejected, bad syntax or domain, disposable | undeliverable | undeliverable |
| Risk signal (role, full mailbox, trap, toxic, typo and others) | risky | risky |
| Catch-all domain | unknown | risky |
| No conclusive answer | unknown | unknown |
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"}'import RocketVerifier from "@rocketverifier/sdk";
// Extra headers are sent with every request this client makes.
const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY, {
headers: { "RocketVerifier-Version": "2026-11-01" },
});
const result = await rv.verify("maya.patel@lakeside-dental.com");import os
import requests
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": "maya.patel@lakeside-dental.com"},
timeout=35,
)
print(res.json()["status"]) # "risky" for a catch-all addressThe header applies to every endpoint that returns a public status:
POST /v1/verifyGET /v1/jobs/{id}/resultsGET /v1/jobs/{id}/download, including thefilter=riskyandfilter=unknownsegments- The
email.verifiedwebhook 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.
| Credential | Default version |
|---|---|
| API key created from November 2026 | 2026-11-01 |
| API key created before November 2026 | 2025-01-01 |
| Organization API key | 2025-01-01 |
OAuth access token (rv_at_) | 2025-01-01 |
| Dashboard | 2026-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.
Find code that treats unknown as catch-all
Search for places that read
status === "unknown"and then checkdomain.acceptAll,reason === "catch_all"orcatch_all_verdict. Under the current version those addresses arrive asriskywithsub_status: "catch_all".Move catch-all handling to the risky branch
Read
catch_all_verdictinside yourriskybranch: sendsend_safe, segmentsend_with_caution, dropavoid. Yourunknownbranch now only ever sees free results to retry afterretry_afterseconds.Send the header everywhere
Add
RocketVerifier-Version: 2026-11-01to every request, including job result reads and downloads, so live checks and stored results use the same mapping.Check dashboards and reports
Counts by
statusshift: catch-all addresses move fromunknowntorisky. Job counters such ascatch_all_countinGET /v1/jobs/{id}and thejob.completedwebhook 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