# API Endpoints

Single Email Validation

Verify a single email address.

**Endpoint:** `POST /verify`

**Request Body:**

```json
{
  "email": "example@domain.com"
}
```

**Response:**

```json
{
  "email": "example@domain.com",
  "details": {
    "syntax": true,
    "domain_exists": true,
    "mx_records": true,
    "mailbox_exists": true,
    "disposable": false,
    "role_based": false,
    "suggestions": []
  },
  "score": 100,
  "status": "VALID",
  "duration_ms": 120
}
```

**Response Fields**

| Field                    | Description                                                        |
| ------------------------ | ------------------------------------------------------------------ |
| `email`                  | The email address that was verified                                |
| `details`                | Object containing detailed verification results                    |
| `details.syntax`         | Whether the email has valid syntax                                 |
| `details.domain_exists`  | Whether the domain exists                                          |
| `details.mx_records`     | Whether the domain has MX records                                  |
| `details.mailbox_exists` | Whether the mailbox likely exists                                  |
| `details.disposable`     | Whether the email is from a disposable domain                      |
| `details.role_based`     | Whether the email is a role-based address (e.g., admin@, support@) |
| `details.suggestions`    | Array of suggested corrections if a typo is detected               |
| `score`                  | Numerical score (0-100) indicating overall email quality           |
| `status`                 | Overall status of the email verification                           |
| `duration_ms`            | Time taken to perform the verification in milliseconds             |

**Status Codes**

| Status Code      | Description                                     |
| ---------------- | ----------------------------------------------- |
| `VALID`          | Email is valid and safe to use                  |
| `PROBABLY_VALID` | Email is likely valid but has some minor issues |
| `INVALID_SYNTAX` | Email syntax is invalid                         |
| `INVALID_DOMAIN` | Email domain does not exist                     |
| `NO_MX_RECORDS`  | Domain does not have MX records                 |
| `DISPOSABLE`     | Email is from a disposable/temporary domain     |
| `ROLE_BASED`     | Email is a role-based address                   |
| `INVALID`        | Email failed multiple checks                    |

#### Bulk Email Validation

Verify multiple email addresses in a single request.

**Endpoint:** `POST /verify/bulk`

**Request Body:**

```json
{
  "emails": [
    "example1@domain.com",
    "example2@domain.com",
    "example3@domain.com"
  ]
}
```

**Response:**

```json
{
  "results": [
    {
      "email": "example1@domain.com",
      "details": {
        "syntax": true,
        "domain_exists": true,
        "mx_records": true,
        "mailbox_exists": true,
        "disposable": false,
        "role_based": false,
        "suggestions": []
      },
      "score": 100,
      "status": "VALID",
      "duration_ms": 120
    },
    {
      "email": "example2@domain.com",
      "details": { ... },
      "score": 80,
      "status": "PROBABLY_VALID",
      "duration_ms": 145
    },
    {
      "email": "example3@domain.com",
      "details": { ... },
      "score": 30,
      "status": "INVALID_DOMAIN",
      "duration_ms": 105
    }
  ]
}
```

**Limitations**

* Maximum of 100 emails per bulk request
* Bulk requests are limited by your plan's bulk quota
* The actual number of emails processed may be limited to your remaining monthly quota