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

# POST /email-validation

> Validate email addresses by checking format, MX records, and detecting role-based or typo domains.

## Endpoint

```
POST https://api.bunny.build/api/v1/email-validation
```

## Authentication

| Header         | Required | Value                    |
| -------------- | -------- | ------------------------ |
| `X-API-Key`    | Yes      | Your API key (`bun_...`) |
| `Content-Type` | Yes      | `application/json`       |

## Overview

Validate an email address across multiple layers: syntax format, DNS MX record existence, and role-based address detection. The response also includes a typo suggestion for common domain misspellings, allowing you to prompt users to correct obvious mistakes before they submit.

## Use cases

* Block invalid addresses at signup to reduce bounce rates
* Scrub lead lists and newsletter databases before campaign sends
* Enforce deliverable email requirements in CRM intake forms
* Surface correction suggestions to users who mistype common domains

## Request body

| Field   | Type   | Required | Description                   |
| ------- | ------ | -------- | ----------------------------- |
| `email` | string | Yes      | The email address to validate |

### Example

```json theme={null}
{
  "email": "user@gmail.com"
}
```

## Response

### 200 OK

| Field        | Type    | Description                                                                                           |
| ------------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `email`      | string  | The email address that was evaluated                                                                  |
| `valid`      | boolean | `true` when both format and MX checks pass                                                            |
| `checks`     | object  | Individual check results: `format` (boolean), `mx` (boolean), `role` (boolean — `true` if role-based) |
| `mx_records` | array   | List of MX records, each with `priority` (integer) and `exchange` (string)                            |
| `suggestion` | string  | Corrected email if a common typo was detected, otherwise `null`                                       |

**Example**

```json theme={null}
{
  "email": "user@gmail.com",
  "valid": true,
  "checks": {
    "format": true,
    "mx": true,
    "role": false
  },
  "mx_records": [
    { "priority": 5, "exchange": "gmail-smtp-in.l.google.com" }
  ],
  "suggestion": null
}
```

**Example with typo suggestion**

```json theme={null}
{
  "email": "user@gamil.com",
  "valid": false,
  "checks": {
    "format": true,
    "mx": false,
    "role": false
  },
  "mx_records": [],
  "suggestion": "user@gmail.com"
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Field 'email' is required."
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## cURL example

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/email-validation \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@gmail.com"}'
```