# Result versions

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

> 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.

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](https://docs.rocketverifier.com/catch-all). 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:

```bash
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"}'
```

Node.js:

```js
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");
```

Python:

```python
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 address
```

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`.

| 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](https://app.rocketverifier.com/dashboard/api-keys) and swap it in.

## Migrate to 2026-11-01

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

**Step 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"`.

**Step 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.

**Step 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.

**Step 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

- [Reading results](https://docs.rocketverifier.com/results)
Every status and sub_status, what it costs and what to do with it.
- [Catch-all domains](https://docs.rocketverifier.com/catch-all)
How the catch-all verdict is reached and what to send to.

## 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.
