https://api.rocketverifier.com/v1/verifyVerify an email
In short
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.
OAuth scope verify:single
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"}'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);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){
"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.
Headers
- Authorizationstringrequired
Bearer <API key or access token>. See authentication. - Idempotency-Keystring
Any unique string, such as a UUID. Retrying with the same key within 24 hours returns the original result without charging again.
- RocketVerifier-Versionstring
2026-11-01or2025-01-01. Picks how catch-all results map ontostatus. Keys created from November 2026 default to2026-11-01. See result versions.
Body
The email address to verify
Seconds to wait for the mail server. Values above 30 are capped at 30. A check that runs out of time returns
unknownand is not charged.
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.
- emailstring
The address as verified, trimmed and with a lowercased domain.
- statusenum
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 version2025-01-01, catch-all addresses are reported asunknowninstead ofrisky.deliverableundeliverableriskyunknown - reasonenum
Legacy reason code derived from
sub_status. Kept for older integrations. Usesub_statusin new code.accepted_emailrejected_emailinvalid_syntaxinvalid_domainno_mx_recorddisposable_emailrole_basedcatch_alltimeoutblockedaccount_disabledmailbox_fullspam_trapknown_complainersuppressedtoxicunknown - sub_statusenum
The precise reason behind
status. See the sub_status reference for what each value means and costs.nonealiasforwardermailbox_not_foundaccount_disableddoes_not_accept_mailinvalid_syntaxinvalid_domaindisposablecatch_allrole_basedmailbox_fullpossible_traptoxicdo_not_mailaccepts_then_bouncesprivacy_relayparked_domainpossible_typodns_errorgreylistedblockedsmtp_timeoutno_connectsmtp_unavailable - catch_all_verdictenum or null
Send recommendation for this exact address when the domain accepts every address. Null for other domains.
send_safesend_with_cautionavoid - verified_atstring (date-time) or null
When the result was produced, in UTC. Earlier than the request when the result came from cache.
- domainobject
Facts about the domain. Yes and no values are strings.
› Show 6 child fields
- namestring
The domain part of the address.
- acceptAllenum
Whether the domain accepts every address (catch-all).
yesnounknown - disposableenum
Whether the domain belongs to a disposable inbox provider.
yesno - freeenum
Whether the domain is a free mailbox provider such as Gmail or Outlook.com.
yesno Confidence that this mailbox is real on a catch-all domain. Set only when
acceptAllisyes.- acceptAllVerdictenum or null
Internal catch-all verdict. Prefer the top-level
catch_all_verdict.send_saferisky_catch_allunlikely
- accountobject
Facts about the mailbox. Yes and no values are strings.
› Show 3 child fields
- roleenum
Whether this is a role address such as info@ or admin@.
yesno - disabledenum
Whether the mailbox is disabled.
yesnounknown - fullMailboxenum
Whether the mailbox is over quota.
yesnounknown
- dnsobject
The mail route found in DNS.
- providerstring or null
Mailbox provider domain, such as
google.comoroutlook.com. Confidence that mail to this address will be delivered. Higher is better.
How well the domain is set up for sending, from its SPF, DKIM and DMARC records.
The score grouped into a tier for simple segmenting.
excellentgoodfairpoorunknown- toxicenum
Whether the address is linked to abuse, complaints or bot signups. A string, not a boolean.
yesnounknown - abuseenum
Whether the address is a known complainer. A string, not a boolean.
yesnounknown - spam_trapenum
Whether the address matches spam trap signals. A string, not a boolean.
yesno - did_you_meanstring or null
Suggested correction when the domain looks like a typo, such as
gmail.comforgmial.com. - activityobject or null
How often and how consistently your own account has verified this address.
› Show 3 child fields
- verification_countinteger
How many times your account verified this address in the last 90 days (up to 50).
How active the address appears.
How consistent its results have been over time.
- evidenceobject 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_providerstring or null
Mail system behind the MX records, such as
google,microsoft_365,outlook_consumer,yahoo,apple,zohoorproton. Null when the MX is not a recognised provider. - gatewaystring or null
Security gateway in front of the mailbox provider, such as
proofpoint,mimecastorbarracuda. - mx_foundboolean or null
Whether the domain publishes MX records or an implicit MX.
- mx_recordstring or null
Highest priority MX host.
- catch_allobject or null
Catch-all details. Null unless the domain accepts every address.
- retry_afterinteger or null
For
unknownresults only. Seconds after which a recheck is likely to get a definite answer. Greylisting servers often say how long to wait. - verdict_sourceenum or null
Which step decided the result.
cachesyntaxlistdnssmtpprecheck - engine_versionstring or null
Version of the verification engine and verdict rules that produced the result, such as
2.2.
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#
deliverable1 creditSend
The mail server explicitly accepted the mailbox.
undeliverable1 creditRemove
The address will bounce: the mailbox, domain or syntax is invalid, or the address is disposable.
risky1 creditSend with care
The address accepts mail but carries a risk: catch-all domain, role address, full mailbox, trap or abuse signals.
unknownFreeRetry later
The mail server gave no conclusive answer. Retry after retry_after seconds.
The reading results guide lists all 25 sub_status values with their cost, and explains scores, catch-all verdicts and typo suggestions.
Try it#
Sandbox addresses return fixed results from the live API. No key, no credits.
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.
Credits#
- 1 credit for every
deliverable,undeliverableandriskyresult. - Free:
unknownresults, addresses on your own suppression list, sandbox addresses, and retries with the sameIdempotency-Key. - Organization keys draw from the shared pool first when pooling is on. See 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 covers each code and how to handle it.
{
"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.
Updated 11 November 2026Suggest an edit