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.

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. Some of these are temporary (retryable); others represent structural limitations.

Risky

Emails with status: "risky" have a moderate deliverability risk.

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.

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([
    'smtp_eof_blocked', 'smtp_timeout', 'smtp_rate_limited',
    'smtp_greylisted', 'mimecast_greylist', 'proofpoint_ad_lookup',
    'policy_temp_fail', 'google_rate_limit', 'm365_ip_rep_block',
    'dns_timeout', 'dns_lookup_error', 'yahoo_api_error',
    'yahoo_api_unavailable', 'yahoo_api_eof',
    'yahoo_api_unavailable_after_fallback', 'internal_verifier_error',
    'rate_limited', 'mx_only_verification_semaphore_timeout',
  ]);
  return result.status === 'unknown' && retryableReasons.has(result.reason);
}