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

# Verify Email Addresses for Deliverability via the API

> Submit any email address for real-time or deep verification. Receive a deliverability verdict synchronously (200) or asynchronously (202) via webhook.

The Email Verification endpoint validates individual email addresses to protect your sender reputation and keep your outreach lists clean. You submit an email with an optional `deepVerification` flag, and Clodura responds immediately with a result if verification completes quickly (`200 OK`), or queues an asynchronous job and returns a `202 Accepted` when the domain requires deeper analysis — such as catch-all domains or high-security mail servers. Once a queued job finishes, Clodura posts the final verdict to your `webhookUrl`.

Standard verification is fast and suitable for most business email addresses. Deep verification takes longer but is the right choice for validating catch-all domains where a standard check cannot determine true deliverability.

<Note>
  **Credit cost:**

  * **Standard verification:** 0.04 credits per request
  * **Deep verification:** 0.1 credits per request
</Note>

<Note>
  **Plan availability:** This endpoint is available on **Free Forever, Max, and PAYG** plans. If you are on an Enterprise or legacy plan not listed, contact [support@clodura.ai](mailto:support@clodura.ai) to discuss access.
</Note>

## Endpoint

`POST /api/v1/verify/email`

## Request

### Headers

| Header         | Value                |
| -------------- | -------------------- |
| `X-API-KEY`    | Your Clodura API key |
| `Content-Type` | `application/json`   |

### Body Parameters

<ParamField body="email" type="string" required>
  The email address you want to verify (e.g., `john@example.com`).
</ParamField>

<ParamField body="deepVerification" type="boolean">
  When `true`, Clodura performs deep verification suitable for catch-all domains and high-security mail servers. Costs 0.1 credits. When `false` (default), standard verification is used at 0.04 credits.
</ParamField>

<ParamField body="webhookUrl" type="string">
  The URL where Clodura will POST the final verification result once processing completes. Strongly recommended for deep verification, where results may not be immediate.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL — Standard Verification theme={null}
  curl --request POST \
    --url https://api.clodura.ai/api/v1/verify/email \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "email": "john@example.com",
      "deepVerification": false,
      "webhookUrl": "https://yourdomain.com/webhooks/clodura"
    }'
  ```

  ```bash cURL — Deep Verification theme={null}
  curl --request POST \
    --url https://api.clodura.ai/api/v1/verify/email \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "email": "john@example.com",
      "deepVerification": true,
      "webhookUrl": "https://yourdomain.com/webhooks/clodura"
    }'
  ```

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

  url = "https://api.clodura.ai/api/v1/verify/email"

  headers = {
      "X-API-KEY": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  # Standard verification (0.04 credits)
  payload = {
      "email": "john@example.com",
      "deepVerification": False,
      "webhookUrl": "https://yourdomain.com/webhooks/clodura"
  }

  # Deep verification (0.1 credits)
  # payload = {
  #     "email": "john@example.com",
  #     "deepVerification": True,
  #     "webhookUrl": "https://yourdomain.com/webhooks/clodura"
  # }

  response = requests.post(url, json=payload, headers=headers)
  print(response.status_code, response.json())
  ```
</CodeGroup>

## Response

### 200 OK — Synchronous Result

Returned when verification completes immediately. The email's deliverability verdict is available in the response body.

<ResponseField name="email" type="string">
  The email address that was verified.
</ResponseField>

<ResponseField name="deepVerification" type="boolean">
  Indicates whether deep verification was used for this request.
</ResponseField>

<ResponseField name="trackingId" type="string">
  A unique document ID for this verification job. Use this to poll for results or match incoming webhook payloads.
</ResponseField>

<ResponseField name="verificationProgress" type="string">
  Current processing state: `In-progress` or `Completed`.
</ResponseField>

<ResponseField name="verificationStatus" type="string">
  The deliverability verdict: `Deliverable`, `Undeliverable`, `Risky (Catch-all)`, or `Pending`.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp indicating when the verification job was created.
</ResponseField>

```json theme={null}
{
  "email": "john@example.com",
  "deepVerification": false,
  "trackingId": "664f1a2b3c4d5e6f7a8b9c0d",
  "verificationProgress": "Completed",
  "verificationStatus": "Deliverable",
  "createdAt": "2024-06-01T10:00:00.000Z"
}
```

### 202 Accepted — Asynchronous Job Queued

Returned when the verification requires more time — typically for deep verification or catch-all domains. The result is delivered to your `webhookUrl` once processing finishes.

<ResponseField name="email" type="string">
  The email address submitted for verification.
</ResponseField>

<ResponseField name="deepVerification" type="boolean">
  Indicates whether deep verification was requested.
</ResponseField>

<ResponseField name="trackingId" type="string">
  A unique identifier for this job. Match this against incoming webhook payloads.
</ResponseField>

<ResponseField name="verificationProgress" type="string">
  Current state: `In-progress`.
</ResponseField>

<ResponseField name="verificationStatus" type="string">
  Current status: `Pending` until the job completes.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of job creation.
</ResponseField>

<ResponseField name="pending" type="boolean">
  Always `true` for `202` responses, confirming the job is queued.
</ResponseField>

```json theme={null}
{
  "email": "john@example.com",
  "deepVerification": true,
  "trackingId": "664f1a2b3c4d5e6f7a8b9c0d",
  "verificationProgress": "In-progress",
  "verificationStatus": "Pending",
  "createdAt": "2024-06-01T10:00:00.000Z",
  "pending": true
}
```

### Webhook Payload Schema

Once verification finishes, Clodura POSTs the following payload to your `webhookUrl`:

| Field                  | Type    | Description                                                       |
| ---------------------- | ------- | ----------------------------------------------------------------- |
| `email`                | string  | The verified email address                                        |
| `deepVerification`     | boolean | `true` if deep verification was used                              |
| `trackingId`           | string  | Document ID — matches the ID in the initial response              |
| `verificationProgress` | string  | `In-progress` or `Completed`                                      |
| `verificationStatus`   | string  | `Deliverable`, `Undeliverable`, `Risky (Catch-all)`, or `Pending` |
| `createdAt`            | string  | ISO 8601 timestamp of job creation                                |

### Verification Status Values

| Status              | Meaning                                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `Deliverable`       | The email address is valid and messages will be accepted.                                                   |
| `Undeliverable`     | The email address does not exist or will permanently reject mail.                                           |
| `Risky (Catch-all)` | The domain accepts all email regardless of whether the mailbox exists — deliverability cannot be confirmed. |
| `Pending`           | Verification is still in progress (only seen in `202` responses).                                           |

## Error Codes

| Status | Meaning                                                                |
| ------ | ---------------------------------------------------------------------- |
| `400`  | Bad request — email format is invalid                                  |
| `402`  | Payment required — credits exhausted; upgrade your plan or add credits |
| `403`  | Forbidden — email verification is not available on your current plan   |
| `500`  | Internal server error — an unexpected error occurred                   |