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

# Verify a Single Email Address in Real-Time

> Use GET /v1/verify to check whether an email address is deliverable in real-time. Results return immediately.

Single verification lets you check one email address on demand and get a result immediately. It's the right choice when you're working one address at a time — for example, validating an address in a tool like Clay, or enriching a record the moment it's retrieved.

## When to use single verification

* **Clay and similar tools** — when your tool doesn't support our bulk verification endpoint.
* **Real-time enrichment** — add deliverability data to a record the moment it's retrieved or created.

<Note>
  **Validating more than one address? Use [bulk verification](/docs/guides/bulk-verification).** Bulk jobs run in the background, so OrbiSearch can spend more time per address — and retry greylisted servers for up to 30 minutes — to return more definitive results than a single timed request. Use synchronous verification only for ad-hoc, single-address checks, or when your tool (such as Clay) doesn't support bulk.
</Note>

## Making a request

To verify an email, send a `GET` request to `/v1/verify` with your email address as a query parameter. Include your API key in the `X-API-Key` header.

<Steps>
  <Step title="Get your API key">
    Sign in to the [OrbiSearch dashboard](https://orbisearch.com/dashboard/api-keys) and copy your API key.
  </Step>

  <Step title="Send the request">
    Call `GET /v1/verify?email=<address>` with your key in the request header.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
        --url "https://api.orbisearch.com/v1/verify?email=jane.doe@acme.com" \
        --header "X-API-Key: YOUR_API_KEY"
      ```

      ```python Python theme={null}
      import requests

      response = requests.get(
          "https://api.orbisearch.com/v1/verify",
          params={"email": "jane.doe@acme.com"},
          headers={"X-API-Key": "YOUR_API_KEY"},
      )

      result = response.json()
      print(result["status"], result["substatus"])
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        "https://api.orbisearch.com/v1/verify?email=jane.doe%40acme.com",
        {
          headers: {
            "X-API-Key": "YOUR_API_KEY",
          },
        }
      );

      const result = await response.json();
      console.log(result.status, result.substatus);
      ```
    </CodeGroup>
  </Step>

  <Step title="Read the response">
    The API returns a JSON object with the verification result. Use the `status` field to decide what to do with the address.

    ```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
    }
    ```
  </Step>
</Steps>

## Interpreting the response

Every response includes a `status` and a more specific `substatus`. Use `status` for the primary decision, and `substatus` for additional detail.

| `status`  | What it means                                                         | Recommended action                 |
| --------- | --------------------------------------------------------------------- | ---------------------------------- |
| `safe`    | The mailbox exists and is accepting mail.                             | Include in outreach and workflows. |
| `risky`   | Deliverability is uncertain (e.g., catch-all domain or policy block). | Review based on your use case.     |
| `invalid` | The address will bounce.                                              | Remove from your list.             |
| `unknown` | A transient error prevented verification.                             | Retry the next day.                |

For a full breakdown of every `substatus` value and what it means, see [Handling Results](/docs/guides/handling-results).

### Response fields

| Field                     | Type            | Description                                                                                               |
| ------------------------- | --------------- | --------------------------------------------------------------------------------------------------------- |
| `email`                   | string          | The email address that was verified.                                                                      |
| `status`                  | string          | Top-level deliverability verdict: `safe`, `risky`, `invalid`, or `unknown`.                               |
| `substatus`               | string          | The specific reason behind the status.                                                                    |
| `explanation`             | string          | A plain-English description of the result.                                                                |
| `email_provider`          | string          | The detected email provider (e.g., `Google Workspace`, `Gmail`).                                          |
| `mx_record`               | string \| null  | The main mail server the domain uses to receive email.                                                    |
| `is_domain_catch_all`     | boolean \| null | Whether the domain accepts mail for any username (catch-all).                                             |
| `is_secure_email_gateway` | boolean         | Whether the domain is protected by a secure email gateway (Proofpoint, Mimecast, Barracuda, Trend Micro). |
| `is_disposable`           | boolean \| null | Whether the address uses a known disposable email service.                                                |
| `is_role_account`         | boolean \| null | Whether the address is a role account (e.g., `support@`, `info@`).                                        |
| `is_free`                 | boolean \| null | Whether the address uses a free email provider (e.g., Gmail, Yahoo).                                      |

<Note>
  `is_domain_catch_all`, `is_disposable`, `is_role_account`, and `is_free` may be `null` when OrbiSearch cannot determine the value with confidence.
</Note>

## The `timeout` parameter

By default, OrbiSearch waits up to 97 seconds for a response from the destination mail server. You can adjust this with the `timeout` query parameter (minimum 3, maximum 97, in seconds).

```bash theme={null}
curl --request GET \
  --url "https://api.orbisearch.com/v1/verify?email=jane.doe@acme.com&timeout=10" \
  --header "X-API-Key: YOUR_API_KEY"
```

<Tip>
  Use a short timeout (3–10 seconds) when you need a quick answer. Use the default or a longer timeout when accuracy matters more than speed. A shorter timeout increases the likelihood of an `unknown` result for slow mail servers.
</Tip>

## Rate limits

The single verification endpoint allows up to **20 requests per second** per API key. If you exceed this limit, the API returns a `429 Too Many Requests` response. Add a retry with exponential backoff to handle this gracefully.

For higher throughput, use the [bulk verification endpoint](/docs/guides/bulk-verification), which processes large lists asynchronously without rate limit concerns.

## Credit cost

Each email verification costs **0.2 credits**. You can check your current credit balance at any time via the API or the [OrbiSearch dashboard](https://orbisearch.com/dashboard).