Skip to content
RocketVerifierDOCS
POSThttps://api.rocketverifier.com/v1/verify

Verify 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"}'
Response 200
{
  "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-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.

Body

  • emailstringrequired

    The email address to verify

  • timeoutinteger3 to 60default 10

    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.

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 version 2025-01-01, catch-all addresses are reported as unknown instead of risky.

    deliverableundeliverableriskyunknown
  • reasonenum

    Legacy reason code derived from sub_status. Kept for older integrations. Use sub_status in new code.

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

    • Whether the domain accepts every address (catch-all).

      yesnounknown
    • 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
    • acceptAllConfidenceinteger or null0 to 100

      Confidence that this mailbox is real on a catch-all domain. Set only when acceptAll is yes.

    • 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
    • Whether the mailbox is disabled.

      yesnounknown
    • Whether the mailbox is over quota.

      yesnounknown
  • dnsobject

    The mail route found in DNS.

    › Show 2 child fields
    • typeenum

      Record type used for delivery.

      MXACNAME
    • recordstring or null

      The record value, such as the MX host.

  • providerstring or null

    Mailbox provider domain, such as google.com or outlook.com.

  • scoreinteger0 to 100

    Confidence that mail to this address will be delivered. Higher is better.

  • authentication_scoreinteger0 to 100

    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
  • 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.com for gmial.com.

  • activityobject or null

    How often and how consistently your own account has verified this address.

    › Show 3 child fields
    • How many times your account verified this address in the last 90 days (up to 50).

    • activity_scoreinteger0 to 100

      How active the address appears.

    • stability_scoreinteger0 to 100

      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, zoho or proton. Null when the MX is not a recognised provider.

  • gatewaystring or null

    Security gateway in front of the mailbox provider, such as proofpoint, mimecast or barracuda.

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

    › Show 4 child fields
    • verdictenum or null

      Same value as catch_all_verdict.

      send_safesend_with_cautionavoid
    • scoreinteger or null0 to 100

      Plausibility that this mailbox is real.

    • methodenum

      How the score was reached.

      patternheuristic
    • reasonsarray of strings

      Plain language reasons behind the score.

  • retry_afterinteger 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_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 credit

Send

The mail server explicitly accepted the mailbox.

undeliverable1 credit

Remove

The address will bounce: the mailbox, domain or syntax is invalid, or the address is disposable.

risky1 credit

Send with care

The address accepts mail but carries a risk: catch-all domain, role address, full mailbox, trap or abuse signals.

unknownFree

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

Errors#

Statuserror.codeWhen it happens
401unauthorizedThe key is missing, malformed or revoked.
401api_key_expiredThe key passed its expiry date. Create a new key or extend it.
402insufficient_creditsThe balance ran out while charging this result.
402api_key_spend_cap_reachedThis key hit its monthly spend cap.
403insufficient_creditsThe balance is zero, so the request is refused before any check runs.
403sandbox_key_restrictedAn rv_test_ key was used on a real address.
403insufficient_scopeThe OAuth token lacks verify:single.
403ip_not_allowedThe key has an IP allowlist that does not include the caller.
422validation_errorThe body is not valid JSON, email is missing, or timeout is out of range.
429rate_limitedToo 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 body
{
  "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