Email Verification Response Schema

Field reference for EmailVerificationResponse — returned by the single and bulk verification endpoints. Covers all status values and all 14 substatus codes.

Both the single verification endpoint (GET /v1/verify) and the bulk results endpoint (GET /v1/bulk/{job_id}/results) return an EmailVerificationResponse object. It contains the overall status, a detailed substatus, a plain-English explanation, the detected email_provider, domain-level signals (mx_record, is_domain_catch_all, is_secure_email_gateway), three boolean enrichment flags that tell you whether the address is disposable, role-based, or from a free provider, and a confidence score for safe results.

Fields

email · string

The email address that was verified. Reflects the address from your request.

status · string

Overall verification result. One of safe, risky, invalid, or unknown. See status values below for descriptions.

substatus · string

The specific reason behind the status. Provides more granular detail than status alone. See substatuses below for all 14 possible values.

explanation · string

A plain-English sentence describing the verification outcome. Suitable for logs, dashboards, and debugging.

email_provider · string

The email service provider associated with the address domain. Examples: Google Workspace, Gmail, Microsoft Outlook.

mx_record · string | null

The main mail server the domain uses to receive email. null if the domain has no mail server configured — when that happens, substatus will be no_mx_records.

is_domain_catch_all · boolean | null

true if the domain accepts mail for any username (catch-all). null if we could not determine whether the domain is catch-all.

is_secure_email_gateway · boolean

true if the domain is protected by a secure email gateway — Proofpoint, Mimecast, Barracuda, or Trend Micro.

is_disposable · boolean | null

true if the address belongs to a known temporary or disposable email service (e.g., Mailinator, Guerrilla Mail). false if it is not. null if the provider could not be determined.

is_role_account · boolean | null

true if the address is a generic role-based account such as info@, support@, or sales@. These addresses typically map to shared inboxes rather than individual recipients. null if it could not be determined.

is_free · boolean | null

true if the address is from a free consumer email provider such as gmail.com, yahoo.com, or hotmail.com. null if the provider could not be determined.

confidence · integer | null

How confident we are in the result, on a 0–100 scale. Returned for safe results only — use the score to balance yield vs bounce rate when filtering deliverable addresses. null for risky, invalid, and unknown results; use status and substatus for those instead.

Status values

Status	Meaning
safe	The mailbox has been confirmed to exist and is accepting mail. Safe to send to.
risky	Deliverability cannot be confirmed. The address may be valid but verification was inconclusive. Use caution when sending.
invalid	The mailbox does not exist or cannot receive mail. Sending will result in a bounce.
unknown	Verification could not be completed due to a transient server issue. OrbiSearch automatically retries these in bulk jobs.

Substatuses

Each substatus maps to a parent status. The table below lists all 14 substatus values, their parent status, and their meaning.

Substatus	Status	Meaning
deliverable	safe	Mailbox confirmed to exist and accept mail.
catch_all	risky	The domain accepts mail sent to any address. Individual mailbox existence cannot be confirmed.
policy_blocked	risky	The recipient’s mail gateway blocked the verification attempt. The email may still be deliverable.
mailbox_not_found	invalid	The mailbox does not exist at this domain.
invalid_syntax	invalid	The email address is malformed and cannot be delivered.
no_mx_records	invalid	The domain has no email servers configured.
mailbox_disabled	invalid	The email account has been deactivated.
mailbox_full	invalid	The mailbox storage quota is full and cannot accept new mail.
greylisted	unknown	The mail server temporarily delayed the verification attempt. OrbiSearch automatically retries greylisted addresses.
timeout	unknown	The target mail server did not respond within the allotted time.
smtp_unreachable	unknown	OrbiSearch could not open a connection to the mail server. The mailbox cannot be verified at this time.
verification_blocked	unknown	The provider has temporarily blocked verification requests.
ip_blocked	unknown	The mail server blocked the verification based on OrbiSearch’s IP.
technical_issue	unknown	Recipient’s mail server returned an unexpected response.