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

# How to Handle Email Verification Results

> Learn how to act on OrbiSearch verification results. Covers recommended actions by status and guidance for cold outreach, data enrichment, and form validation.

OrbiSearch returns a `status` and `substatus` for every verified address, along with additional flags that give you more detail about the nature of the mailbox. Knowing how to act on these values is the difference between a clean, high-performing list and one that damages your sender reputation. This guide walks you through the decision-making process for the most common workflows.

## Understanding status and substatus

Every result has two primary fields:

* **`status`** — the top-level deliverability verdict. Use this for your primary decision.
* **`substatus`** — the specific reason behind the status. Use this for finer-grained filtering or to log more detail about why an address was flagged.

```json theme={null}
{
  "email": "jane.doe@acme.com",
  "status": "safe",
  "substatus": "deliverable",
  "explanation": "The mailbox exists and is accepting mail.",
  "email_provider": "Google Workspace",
  "mx_record": "aspmx.l.google.com",
  "is_domain_catch_all": false,
  "is_secure_email_gateway": false,
  "is_disposable": false,
  "is_role_account": false,
  "is_free": false
}
```

The `explanation` field contains a plain-English description of the result — useful for logging, debugging, or displaying context in an internal tool.

### Status values

| Status    | What it means                                                                 |
| --------- | ----------------------------------------------------------------------------- |
| `safe`    | The mailbox exists and is accepting mail.                                     |
| `risky`   | Deliverability is uncertain — the address may or may not accept mail.         |
| `invalid` | The address will bounce. It should not be sent to.                            |
| `unknown` | A transient error prevented verification. The result may change if you retry. |

### Substatus values

| Substatus              | Status    | Description                                                                      |
| ---------------------- | --------- | -------------------------------------------------------------------------------- |
| `deliverable`          | `safe`    | Mailbox confirmed as accepting mail.                                             |
| `catch_all`            | `risky`   | The domain accepts mail for any address; individual mailbox cannot be confirmed. |
| `policy_blocked`       | `risky`   | The mail server refused to verify the address due to a policy restriction.       |
| `mailbox_not_found`    | `invalid` | The mailbox does not exist on the domain.                                        |
| `invalid_syntax`       | `invalid` | The address is not a valid email format.                                         |
| `no_mx_records`        | `invalid` | The domain has no mail server configured.                                        |
| `mailbox_disabled`     | `invalid` | The mailbox exists but has been disabled.                                        |
| `mailbox_full`         | `invalid` | The mailbox exists but is full and cannot accept new mail.                       |
| `greylisted`           | `unknown` | The mail server temporarily deferred the verification attempt.                   |
| `timeout`              | `unknown` | Verification timed out before the mail server responded.                         |
| `smtp_unreachable`     | `unknown` | Could not open a connection to the mail server.                                  |
| `verification_blocked` | `unknown` | The mail server actively blocked the verification request.                       |
| `ip_blocked`           | `unknown` | The verification request was blocked at the IP level.                            |
| `technical_issue`      | `unknown` | Recipient's mail server returned an unexpected response.                         |

## Recommended actions by status

<Tabs>
  <Tab title="safe">
    The address is deliverable. Include it in your outreach or workflow without restriction.

    **Action:** Proceed normally.

    **Exception:** A `safe` address with `is_role_account: true` (e.g., `info@company.com`) may technically be deliverable but receive low engagement. Consider filtering role accounts for cold outreach.
  </Tab>

  <Tab title="risky">
    The deliverability of this address is uncertain. Whether to include it depends on your risk tolerance and use case.

    **Action:** Review based on your workflow. See [use-case guidance](#use-case-guidance) below.

    Common risky substatuses:

    * `catch_all` — the domain accepts everything; you won't know if the specific mailbox exists until you send.
    * `policy_blocked` — the server refused to answer; the address may be valid.
    * `role_account` — a generic shared inbox such as `info@` or `support@`; may be deliverable but typically low engagement.
  </Tab>

  <Tab title="invalid">
    The address will bounce. Sending to it harms your sender reputation.

    **Action:** Remove from your list immediately. Do not send to `invalid` addresses under any circumstances.

    If you encounter a high volume of `invalid_syntax` results, investigate how the addresses were collected — it may indicate a data quality issue at the source.
  </Tab>

  <Tab title="unknown">
    OrbiSearch could not complete the verification due to a transient condition. The address may be valid or invalid.

    **Action:** Retry after 24 hours. Most `unknown` results resolve on a subsequent attempt. If an address consistently returns `unknown` across multiple retries, treat it as risky.

    Do not discard `unknown` addresses without retrying — you may be discarding valid contacts.
  </Tab>
</Tabs>

## Use-case guidance

Different workflows call for different thresholds. Use the tabs below to find guidance for your situation.

<Tabs>
  <Tab title="Cold outreach">
    Cold email campaigns are sensitive to bounce rates and spam complaints. A high bounce rate damages your sending domain's reputation and can get your account suspended by your email service provider.

    **Recommended approach:** Only send to `safe` addresses.

    * **Include:** `safe`
    * **Exclude:** `risky`, `invalid`, `unknown`

    If your list is large and you want to maximize reach, you may choose to include `risky` addresses with a `catch_all` substatus — these are common on corporate domains and often deliverable. Monitor bounce rates closely if you do this.

    <Warning>
      Never send to `invalid` addresses. A single campaign to a list with high `invalid` counts can permanently damage your sender reputation.
    </Warning>

    **Additional filters for cold outreach:**

    * Exclude `is_role_account: true` — role accounts rarely engage with cold email and often route to a shared inbox or spam filter.
    * Consider excluding `is_free: true` if you're targeting businesses — free addresses may indicate personal rather than professional contacts.
  </Tab>

  <Tab title="Data enrichment / analytics">
    If you're building a dataset, running analytics, or enriching CRM records rather than sending email, you can afford a more permissive threshold.

    **Recommended approach:** Retain `safe` and `risky`; remove `invalid`; decide on `unknown` based on data completeness needs.

    * **Retain:** `safe`, `risky`
    * **Remove or flag:** `invalid`
    * **Flag for review:** `unknown`

    For analytics, retaining `risky` addresses gives you a more complete picture of your dataset. You can always apply stricter filters later if you decide to run a sending campaign.

    Use `substatus` and the additional flags to add metadata to each record rather than simply including or excluding:

    ```json theme={null}
    {
      "email": "info@company.com",
      "status": "risky",
      "substatus": "role_account",
      "is_role_account": true,
      "is_free": false
    }
    ```
  </Tab>

  <Tab title="Point-of-entry validation">
    When validating an address as a user types it — on a signup form, checkout page, or lead capture form — your goal is to prevent obviously bad addresses from entering your system while avoiding false rejections that frustrate legitimate users.

    **Recommended approach:** Reject `invalid` and disposable addresses. Flag `risky` for review or a soft warning. Accept `safe`.

    * **Accept:** `safe`
    * **Reject:** `invalid`, and any address where `is_disposable: true`
    * **Flag or soft-warn:** `risky` (display a message like "We couldn't fully verify this address — please double-check it")
    * **Accept but flag:** `unknown` (do not block the user; retry verification in the background)

    <Tip>
      Use the `timeout` parameter to control how long the API waits for a response. For real-time validation, a timeout of 5–10 seconds keeps the user experience fast. You can always re-verify the address in the background with a longer timeout if the first attempt returns `unknown`.
    </Tip>

    For consumer-facing forms where disposable emails are a fraud or abuse vector, set `is_disposable: true` as a hard rejection criterion in addition to `status: invalid`.
  </Tab>
</Tabs>

## Using the additional flags

Each result includes three boolean flags that give you more detail about the nature of the address. These are independent of `status` and can be used to apply additional filters on top of the primary deliverability verdict.

| Flag              | What it means                                                                                            | When to filter on it                                                                                               |
| ----------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `is_disposable`   | The address uses a known temporary or disposable email service.                                          | Reject on signup forms to prevent throwaway registrations. Exclude from outreach where quality matters.            |
| `is_role_account` | The address is a functional account rather than a personal one (e.g., `support@`, `admin@`, `noreply@`). | Exclude from cold outreach where personalized engagement is the goal. Role accounts typically have low open rates. |
| `is_free`         | The address uses a free consumer email provider (e.g., Gmail, Yahoo, Outlook.com).                       | Use as a signal for B2B vs. B2C segmentation. Not a quality issue on its own.                                      |

<Note>
  These flags may be `null` when OrbiSearch cannot determine the value with confidence — for example, when the domain is private or not well-known. Treat `null` the same as `false` unless you have a reason to be strict.
</Note>

## What to do with `unknown` results

`unknown` results are almost always temporary. They typically occur because:

* The destination mail server was slow or temporarily unreachable (`smtp_unreachable`, `timeout`)
* The server applied greylisting (`greylisted`) — a technique where the server temporarily rejects unknown senders and expects a retry
* The verification was blocked at the network level (`verification_blocked`, `ip_blocked`)

**What to do:**

1. Wait 24 hours before retrying — transient issues often resolve within 24 hours.
2. Re-verify using `GET /v1/verify` or by resubmitting a bulk job containing only the `unknown` addresses.
3. If an address returns `unknown` consistently across multiple retries over 24+ hours, treat it as `risky` for outreach purposes.

OrbiSearch handles greylisting retries automatically in bulk jobs. If your job finishes with a `partial_complete_retrying` status, wait for it to transition to `complete` before retrieving results — the final pass may resolve some `unknown` entries.

## What to do when a safe email bounces

A `safe` result means OrbiSearch confirmed the mailbox was accepting mail at the time of verification. However, mailboxes can be deleted or disabled after verification, or a sending issue may exist on your side.

If you receive a bounce for an address that was marked `safe`:

1. **Check the bounce type.** A hard bounce (permanent failure) on a previously `safe` address may mean the mailbox was closed after verification. A soft bounce (temporary failure) may be unrelated to deliverability.
2. **Re-verify the address.** Run it through `GET /v1/verify` again to get a fresh result. If it now returns `invalid`, remove it from your list.
3. **Check your sending setup.** Bounces can also result from issues with your sending domain's SPF, DKIM, or DMARC configuration — not just the recipient address.
4. **Contact support** if you're seeing a pattern of bounces on `safe` addresses that re-verify as `safe`. This may indicate a data issue that OrbiSearch support can investigate.