Verification Reasons

Every verification result includes a reason field that explains why the email received its status. Use this reference to build precise filtering logic, diagnose unexpected results, and tune your sending strategy.

How reasons work

The reason field appears in all verification responses alongside the status field:

{
  "email": "user@example.com",
  "status": "valid",
  "reason": "smtp_deliverable"
}

Reasons are stable string identifiers — you can use them directly in filtering rules or downstream conditional logic.

How each mailbox type is verified

The reason you get depends on how the recipient's provider can be checked:

• Business domains (Google Workspace, Microsoft 365, self-hosted mail servers) get a live SMTP RCPT check against the exact mailbox. A random address on the same domain is probed first, so catch-all domains, Microsoft 365 internal relay, and security gateways in accept-all mode are reported as catchall rather than valid.
• Gmail gets a live SMTP RCPT check.
• Yahoo, AOL, Outlook.com, Hotmail, Live, and MSN block SMTP verification, so they are checked through provider-specific account lookups. These return yahoo_api_* or microsoft_api_* reasons and confirm whether the account exists.
• GMX, web.de, Mail.ru, Yandex, and other regional providers are verified with provider-specific pacing. Rate limits, greylisting, and refused checks lead to more unknown results.
• Apple iCloud, Proton, and Tuta allow no reliable check, so their addresses always return unknown with smtp_unverifiable.

unknown results are never billed, whatever the reason.

Valid

Emails with status: "valid" are confirmed deliverable.

Invalid

Emails with status: "invalid" should be removed from your list — delivery is not possible.

Unknown

Emails with status: "unknown" could not be conclusively verified. Unknown results are never billed. Some are temporary (retryable); others represent structural limitations.

Catch-all

Emails with status: "catchall" belong to domains that accept mail for all addresses. Individual deliverability cannot be confirmed.

Role

Emails with status: "role" belong to shared inboxes (e.g. info@, support@, noreply@). These addresses are typically deliverable but have low engagement.

Role addresses inherit the reason from their underlying SMTP check — no dedicated reason codes exist for this status. For example, a role address that passes SMTP will show reason: "smtp_deliverable".

Disposable

Emails with status: "disposable" belong to temporary email services. Accepting these usually leads to low-quality signups.

Risky (older results only)

New verifications no longer return status: "risky". Its only source, the Spamhaus Domain Blocklist check, was removed on 2026-09-11. You may still see risky on results created before that date.

On those older results, risky meant the address was most likely deliverable but the recipient domain was listed by Spamhaus for spam, phishing, malware, or botnet C&C activity. The risk_reasons array explains why:

Using reasons in filtering

You can combine status and reason for precise list segmentation. For example, to keep unknown emails that are only unknown due to temporary issues:

function isRetryableUnknown(result) {
  const retryableReasons = new Set([
    'capacity_deferred', 'context_cancelled', 'dns_lookup_error',
    'dns_resolution_failed', 'dns_timeout', 'google_rate_limit',
    'internal_verifier_error', 'm365_ip_rep_block', 'microsoft_api_error',
    'microsoft_api_unavailable', 'mimecast_greylist',
    'mx_only_verification_semaphore_timeout', 'policy_temp_fail',
    'proofpoint_ad_lookup', 'rate_limited', 'smtp_550_unclassified',
    'smtp_connection_failed', 'smtp_egress_unavailable', 'smtp_eof_blocked',
    'smtp_greylisted', 'smtp_rate_check_failed', 'smtp_rate_limited',
    'smtp_rate_wait_failed', 'smtp_timeout', 'unitedinternet_api_error',
    'yahoo_api_eof', 'yahoo_api_error', 'yahoo_api_rate_limited',
    'yahoo_api_unavailable',
  ]);
  return result.status === 'unknown' && retryableReasons.has(result.reason);
}