> ## Documentation Index
> Fetch the complete documentation index at: https://orbisearch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/api-reference/verify-email)) and the bulk results endpoint ([GET /v1/bulk/\{job\_id}/results](/docs/api-reference/bulk-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

<ResponseField name="email" type="string">
  The email address that was verified. Reflects the address from your request.
</ResponseField>

<ResponseField name="status" type="string">
  Overall verification result. One of `safe`, `risky`, `invalid`, or `unknown`. See [status values](#status-values) below for descriptions.
</ResponseField>

<ResponseField name="substatus" type="string">
  The specific reason behind the status. Provides more granular detail than `status` alone. See [substatuses](#substatuses) below for all 14 possible values.
</ResponseField>

<ResponseField name="explanation" type="string">
  A plain-English sentence describing the verification outcome. Suitable for logs, dashboards, and debugging.
</ResponseField>

<ResponseField name="email_provider" type="string">
  The email service provider associated with the address domain. Examples: `Google Workspace`, `Gmail`, `Microsoft Outlook`.
</ResponseField>

<ResponseField name="mx_record" type="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`.
</ResponseField>

<ResponseField name="is_domain_catch_all" type="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.
</ResponseField>

<ResponseField name="is_secure_email_gateway" type="boolean">
  `true` if the domain is protected by a secure email gateway — Proofpoint, Mimecast, Barracuda, or Trend Micro.
</ResponseField>

<ResponseField name="is_disposable" type="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.
</ResponseField>

<ResponseField name="is_role_account" type="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.
</ResponseField>

<ResponseField name="is_free" type="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.
</ResponseField>

<ResponseField name="confidence" type="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.
</ResponseField>

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