# Verify an email

Source: https://docs.rocketverifier.com/api/verify
Endpoint: `POST https://api.rocketverifier.com/v1/verify` (OAuth scope `verify:single`)

> Send one address in the JSON body. You get back a status (deliverable, undeliverable, risky or unknown), the sub_status that explains it, a 0 to 100 score and the evidence behind the verdict. Most answers arrive in under half a second; a live SMTP check takes 1 to 3 seconds. Each result costs 1 credit and unknown results are free.

cURL:

```bash
curl -X POST https://api.rocketverifier.com/v1/verify \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "maya@northwind.io"}'
```

Node.js:

```js
import RocketVerifier from "@rocketverifier/sdk";

const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY);
const result = await rv.verify("maya@northwind.io");

if (result.status === "deliverable") {
  // safe to send
}
console.log(result.subStatus, result.score);
```

Python:

```python
import os
from rocketverifier import RocketVerifier

rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"])
result = rv.verify("maya@northwind.io")

if result.status == "deliverable":
    pass  # safe to send
print(result.sub_status, result.score)
```

Response 200:

```json
{
  "email": "maya@northwind.io",
  "status": "deliverable",
  "sub_status": "none",
  "score": 97,
  "catch_all_verdict": null,
  "did_you_mean": null,
  "domain": {
    "name": "northwind.io",
    "acceptAll": "no",
    "disposable": "no",
    "free": "no"
  },
  "account": { "role": "no", "disabled": "no", "fullMailbox": "no" },
  "provider": "google.com",
  "smtp_provider": "google",
  "mx_record": "aspmx.l.google.com",
  "deliverability_tier": "excellent",
  "verdict_source": "smtp",
  "retry_after": null,
  "verified_at": "2026-11-11T09:42:17Z"
}
```

## Request

Send a JSON body with the address. Authenticate with an API key, or with an OAuth access token that has the `verify:single` scope.

- `Authorization` (string, required):

`Bearer <API key or access token>`. See [authentication](https://docs.rocketverifier.com/authentication).

- `Idempotency-Key` (string):

Any unique string, such as a UUID. Retrying with the same key within 24 hours returns the original result without charging again.

- `RocketVerifier-Version` (string):

`2026-11-01` or `2025-01-01`. Picks how catch-all results map onto `status`. Keys created from November 2026 default to `2026-11-01`. See [result versions](https://docs.rocketverifier.com/versioning).

**Body**

| Field | Type | Description |
| --- | --- | --- |
| `email` | string | The email address to verify required |
| `timeout` | integer | Seconds to wait for the mail server. Values above 30 are capped at 30. A check that runs out of time returns `unknown` and is not charged. 3 to 60; default 10 |

## Response

A `200` response is a single result object. Branch on `status`, read `sub_status` for the reason, and use the rest for segmenting, audits and debugging.

| Field | Type | Description |
| --- | --- | --- |
| `email` | string | The address as verified, trimmed and with a lowercased domain. |
| `status` | enum | The field to branch on. `deliverable`: the mail server confirmed the mailbox. `undeliverable`: the address will bounce or is disposable. `risky`: it accepts mail but carries a risk such as a catch-all domain, role address, full mailbox or trap signals. `unknown`: no conclusive answer, never charged. With result version `2025-01-01`, catch-all addresses are reported as `unknown` instead of `risky`. one of `deliverable`, `undeliverable`, `risky`, `unknown` |
| `reason` | enum | Legacy reason code derived from `sub_status`. Kept for older integrations. Use `sub_status` in new code. one of `accepted_email`, `rejected_email`, `invalid_syntax`, `invalid_domain`, `no_mx_record`, `disposable_email`, `role_based`, `catch_all`, `timeout`, `blocked`, `account_disabled`, `mailbox_full`, `spam_trap`, `known_complainer`, `suppressed`, `toxic`, `unknown` |
| `sub_status` | enum | The precise reason behind `status`. See the sub_status reference for what each value means and costs. one of `none`, `alias`, `forwarder`, `mailbox_not_found`, `account_disabled`, `does_not_accept_mail`, `invalid_syntax`, `invalid_domain`, `disposable`, `catch_all`, `role_based`, `mailbox_full`, `possible_trap`, `toxic`, `do_not_mail`, `accepts_then_bounces`, `privacy_relay`, `parked_domain`, `possible_typo`, `dns_error`, `greylisted`, `blocked`, `smtp_timeout`, `no_connect`, `smtp_unavailable` |
| `catch_all_verdict` | enum or null | Send recommendation for this exact address when the domain accepts every address. Null for other domains. one of `send_safe`, `send_with_caution`, `avoid` |
| `verified_at` | string (date-time) or null | When the result was produced, in UTC. Earlier than the request when the result came from cache. |
| `domain` | object | Facts about the domain. Yes and no values are strings. |
| `domain.name` | string | The domain part of the address. |
| `domain.acceptAll` | enum | Whether the domain accepts every address (catch-all). one of `yes`, `no`, `unknown` |
| `domain.disposable` | enum | Whether the domain belongs to a disposable inbox provider. one of `yes`, `no` |
| `domain.free` | enum | Whether the domain is a free mailbox provider such as Gmail or Outlook.com. one of `yes`, `no` |
| `domain.acceptAllConfidence` | integer or null | Confidence that this mailbox is real on a catch-all domain. Set only when `acceptAll` is `yes`. 0 to 100 |
| `domain.acceptAllVerdict` | enum or null | Internal catch-all verdict. Prefer the top-level `catch_all_verdict`. one of `send_safe`, `risky_catch_all`, `unlikely` |
| `account` | object | Facts about the mailbox. Yes and no values are strings. |
| `account.role` | enum | Whether this is a role address such as info@ or admin@. one of `yes`, `no` |
| `account.disabled` | enum | Whether the mailbox is disabled. one of `yes`, `no`, `unknown` |
| `account.fullMailbox` | enum | Whether the mailbox is over quota. one of `yes`, `no`, `unknown` |
| `dns` | object | The mail route found in DNS. |
| `dns.type` | enum | Record type used for delivery. one of `MX`, `A`, `CNAME` |
| `dns.record` | string or null | The record value, such as the MX host. |
| `provider` | string or null | Mailbox provider domain, such as `google.com` or `outlook.com`. |
| `score` | integer | Confidence that mail to this address will be delivered. Higher is better. 0 to 100 |
| `authentication_score` | integer | How well the domain is set up for sending, from its SPF, DKIM and DMARC records. 0 to 100 |
| `deliverability_tier` | enum | The score grouped into a tier for simple segmenting. one of `excellent`, `good`, `fair`, `poor`, `unknown` |
| `toxic` | enum | Whether the address is linked to abuse, complaints or bot signups. A string, not a boolean. one of `yes`, `no`, `unknown` |
| `abuse` | enum | Whether the address is a known complainer. A string, not a boolean. one of `yes`, `no`, `unknown` |
| `spam_trap` | enum | Whether the address matches spam trap signals. A string, not a boolean. one of `yes`, `no` |
| `did_you_mean` | string or null | Suggested correction when the domain looks like a typo, such as `gmail.com` for `gmial.com`. |
| `activity` | object or null | How often and how consistently your own account has verified this address. |
| `activity.verification_count` | integer | How many times your account verified this address in the last 90 days (up to 50). |
| `activity.activity_score` | integer | How active the address appears. 0 to 100 |
| `activity.stability_score` | integer | How consistent its results have been over time. 0 to 100 |
| `evidence` | object or null | The raw checks behind the verdict (DNS, MX, SMTP replies) and, on catch-all domains, the reasoning behind the plausibility score. Use it for audits and debugging. Its shape varies by path, so do not parse it in application logic. |
| `smtp_provider` | string or null | Mail system behind the MX records, such as `google`, `microsoft_365`, `outlook_consumer`, `yahoo`, `apple`, `zoho` or `proton`. Null when the MX is not a recognised provider. |
| `gateway` | string or null | Security gateway in front of the mailbox provider, such as `proofpoint`, `mimecast` or `barracuda`. |
| `mx_found` | boolean or null | Whether the domain publishes MX records or an implicit MX. |
| `mx_record` | string or null | Highest priority MX host. |
| `catch_all` | object or null | Catch-all details. Null unless the domain accepts every address. |
| `catch_all.verdict` | enum or null | Same value as `catch_all_verdict`. one of `send_safe`, `send_with_caution`, `avoid` |
| `catch_all.score` | integer or null | Plausibility that this mailbox is real. 0 to 100 |
| `catch_all.method` | enum | How the score was reached. one of `pattern`, `heuristic` |
| `catch_all.reasons` | array of strings | Plain language reasons behind the score. |
| `retry_after` | integer or null | For `unknown` results only. Seconds after which a recheck is likely to get a definite answer. Greylisting servers often say how long to wait. |
| `verdict_source` | enum or null | Which step decided the result. one of `cache`, `syntax`, `list`, `dns`, `smtp`, `precheck` |
| `engine_version` | string or null | Version of the verification engine and verdict rules that produced the result, such as `2.2`. |

> **Warning: Yes and no fields are strings**
>
> `domain.disposable`, `domain.acceptAll`, `account.role` and similar fields hold `"yes"`, `"no"` or `"unknown"`. The string `"no"` is truthy in JavaScript and PHP, so compare explicitly.

## What to do with each status

| status | What to do | Meaning | Cost |
| --- | --- | --- | --- |
| `deliverable` | Send | The mail server explicitly accepted the mailbox. | 1 credit |
| `undeliverable` | Remove | The address will bounce: the mailbox, domain or syntax is invalid, or the address is disposable. | 1 credit |
| `risky` | Send with care | The address accepts mail but carries a risk: catch-all domain, role address, full mailbox, trap or abuse signals. | 1 credit |
| `unknown` | Retry later | The mail server gave no conclusive answer. Retry after retry_after seconds. | Free |

The [reading results guide](https://docs.rocketverifier.com/results) lists all 25 `sub_status` values with their cost, and explains scores, catch-all verdicts and typo suggestions.

## Try it

Try the sandbox addresses live at https://docs.rocketverifier.com/api/verify#try-it (no key needed).

These fixed results come from `POST /v1/verify`. In bulk jobs, sandbox addresses run through the full engine like any other address. The full list and how to test bulk flows are in [sandbox and testing](https://docs.rocketverifier.com/sandbox).

## Credits

- **1 credit** for every `deliverable`, `undeliverable` and `risky` result.
- **Free:** `unknown` results, addresses on your own suppression list, sandbox addresses, and retries with the same `Idempotency-Key`.
- Organization keys draw from the shared pool first when pooling is on. See [teams](https://docs.rocketverifier.com/teams).

## Errors

| Status | `error.code` | When it happens |
| --- | --- | --- |
| 401 | `unauthorized` | The key is missing, malformed or revoked. |
| 401 | `api_key_expired` | The key passed its expiry date. Create a new key or extend it. |
| 402 | `insufficient_credits` | The balance ran out while charging this result. |
| 402 | `api_key_spend_cap_reached` | This key hit its monthly spend cap. |
| 403 | `insufficient_credits` | The balance is zero, so the request is refused before any check runs. |
| 403 | `sandbox_key_restricted` | An `rv_test_` key was used on a real address. |
| 403 | `insufficient_scope` | The OAuth token lacks `verify:single`. |
| 403 | `ip_not_allowed` | The key has an IP allowlist that does not include the caller. |
| 422 | `validation_error` | The body is not valid JSON, `email` is missing, or `timeout` is out of range. |
| 429 | `rate_limited` | Too many requests. Wait for the `Retry-After` seconds. |

Every error uses the same shape. The [errors reference](https://docs.rocketverifier.com/errors) covers each code and how to handle it.

Error body:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "You don't have enough credits for this operation",
    "details": { "required": 1, "available": 0 }
  }
}
```

## 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. Check again after the number of seconds in `retry_after`. Addresses on your own suppression list are also free.

### How long does a verification take?

Most results return in under 400 milliseconds because they are decided by syntax, DNS, list checks or cache. Results that need a live SMTP conversation typically take 1 to 3 seconds. Set `timeout` to cap the wait.

### What should I do with a catch-all result?

Read `catch_all_verdict`. Send to `send_safe` addresses, send `send_with_caution` addresses only to engaged segments, and drop `avoid` addresses. The catch-all guide explains how the verdict is reached.

### Can I test without spending credits?

Yes. Addresses at `@sandbox.rocketverifier.com` return fixed results without a key or credits. Use them in tests and CI, or try them on this page.

### Are the yes and no fields booleans?

No. Fields such as `domain.disposable` and `account.role` are the strings `"yes"`, `"no"` or `"unknown"`. Compare them explicitly, for example `result.domain.disposable === "yes"`. The Node.js and Python SDKs convert them to booleans.
