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

# Verify email addresses

> Verify a single email in real time or process thousands in bulk using the v2 Email Verification API.

Use the Email Verification API to check whether email addresses are deliverable — in real time for single addresses, or asynchronously for lists.

## Choose the right method

| | Real-time | Batch |
| - | - | - |
| **Use when** | Validating at point of entry (form submission, CRM sync) | Cleaning a list of 10+ addresses |
| **Endpoint** | `POST /v2/email/verify` | `POST /v2/email/verify/batch` |
| **Response** | Immediate | Async — poll job status, then download results |
| **Best for** | Live enrichment, single lookups | Bulk list cleaning, pre-send scrubbing |

## Verify a single email

```bash theme={null}
curl -X POST https://api.revenuebase.ai/v2/email/verify \
  -H "x-key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"email": "jamie.morgan@acmecorp.com"}'
```

**Response:**

```json theme={null}
{
  "email": "jamie.morgan@acmecorp.com",
  "status": "Valid"
}
```

Add `?metadata=true` to include additional fields in the response:

```json theme={null}
{
  "email": "jamie.morgan@acmecorp.com",
  "status": "Valid",
  "domain": "acmecorp.com",
  "timestamp": "2024-01-15T10:30:00",
  "mx_record_present": true,
  "mx_record_checked": "checked",
  "email_provider": "Google",
  "security_gateway": null,
  "reason": null
}
```

For addresses behind a security gateway or that fail verification, `security_gateway` and `reason` are populated instead of `null`:

```json theme={null}
{
  "email": "jordan.lee@northwind.com",
  "status": "Invalid",
  "domain": "northwind.com",
  "timestamp": "2024-01-15T10:31:00",
  "mx_record_present": true,
  "mx_record_checked": "checked",
  "email_provider": "Microsoft",
  "security_gateway": "Proofpoint",
  "reason": "mailbox_not_found"
}
```

## Understand the response fields

| Field | Values | What it means |
| - | - | - |
| `status` | `Valid`, `Invalid`, `Unknown` | Whether the address is deliverable. Use `Valid` for outbound sends. Deducts 1 credit on `Valid` or `Invalid`. |
| `domain` | string | Domain of the email address. Returned with `?metadata=true`. |
| `mx_record_present` | `true` / `false` | Whether a valid MX record exists for the domain. Returned with `?metadata=true`. |
| `email_provider` | `Google`, `Microsoft`, `Unknown` | Detected email provider. Returned with `?metadata=true`. |
| `security_gateway` | string | Detected security gateway, if any. Returned with `?metadata=true`. |
| `reason` | string | Reason for `Invalid` or `Unknown` status. Returned with `?metadata=true`. |

## Process a batch

Submit a `.csv` or `.json` file and track the job using the [Jobs](/api-reference/v2/overview) endpoints.

<Steps>
  <Step title="Submit the batch">
    Upload your file in a single request. Returns a `process_id` to track the job.

    ```bash theme={null}
    curl -X POST https://api.revenuebase.ai/v2/email/verify/batch \
      -H "x-key: {YOUR_API_KEY}" \
      -F "requested_file=@emails.csv"
    ```
  </Step>

  <Step title="Poll for status">
    ```bash theme={null}
    curl https://api.revenuebase.ai/v2/jobs/{PROCESS_ID} \
      -H "x-key: {YOUR_API_KEY}"
    ```

    Poll until `current_status` is `COMPLETED`. Use a reasonable interval (e.g. every 5–10 seconds for small batches).
  </Step>

  <Step title="Download the results">
    ```bash theme={null}
    curl https://api.revenuebase.ai/v2/jobs/{PROCESS_ID}/download \
      -H "x-key: {YOUR_API_KEY}"
    ```

    Returns the processed output file with a `status` column added for each address.
  </Step>
</Steps>

## Manage batch jobs

| Endpoint | What it does |
| - | - |
| `GET /v2/jobs` | List active (queued or processing) batch jobs |
| `GET /v2/jobs/{process_id}` | Get current status of a specific job |
| `POST /v2/jobs/{process_id}/cancel` | Cancel a job before it completes |
| `GET /v2/jobs/{process_id}/download` | Download results when the job is complete |

## Next steps

See the endpoint reference for `POST /v2/email/verify` and `POST /v2/email/verify/batch` in the sidebar for full parameter and response details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.