# Check an email

POST /v1/check: request format, authentication, response fields and disposable email detection results.

```http
POST /v1/check
```

## Request

`https://api.irondome.dev/v1/check`

Send a Bearer API key and a JSON body with one `email` field.

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

| Requirement | Value |
| --- | --- |
| Authorization | `Bearer YOUR_API_KEY` |
| Content-Type | `application/json` |
| Body limit | 1,024 UTF-8 bytes, including JSON syntax |
| Body fields | One string field: `email` |

Send a known-length body with `Content-Length`. HTTP clients normally set this for a JSON string. Streamed bodies without a length are rejected.

Your authorized plan determines [quota and billing](/docs/plans). Additional JSON fields are rejected.

### Example request

```sh
curl --fail-with-body --request POST 'https://api.irondome.dev/v1/check' \
  --header "Authorization: Bearer $IRONDOME_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"email":"person@example.com"}'
```

Keep the API key in trusted server configuration. An address is checked using the service's normalization rules; clients should submit the user's address rather than implementing a separate disposable detector.

## Response

A successful request returns HTTP `200`:

```json
{
  "provider": "custom",
  "valid": true,
  "disposable": false,
  "reason": "not_listed"
}
```

| Field | Meaning |
| --- | --- |
| `provider` | `gmail`, `microsoft`, `icloud`, `proton`, `yahoo`, or `custom` |
| `valid` | The email passed syntax and normalization checks |
| `disposable` | Whether the detector classifies the address as disposable |
| `reason` | The matching rule, described below |

Invalid email syntax returns HTTP `422`, rather than a successful response with `valid: false`.

## Detection reasons

| Reason | Meaning |
| --- | --- |
| `blocked_email` | The normalized address matches a blocked address |
| `blocked_domain` | The domain or a parent domain matches a blocked domain |
| `allowed_domain` | The domain matches an allowed domain |
| `not_listed` | No matching rule was found |

These results do not verify mailbox ownership, existence, or deliverability.

### A disposable result

An illustrative blocked-domain result is still HTTP `200` because the check succeeded:

```json
{
  "provider": "custom",
  "valid": true,
  "disposable": true,
  "reason": "blocked_domain"
}
```

Use `disposable` as your decision field. The `reason` explains the classification; it is not a separate success or error status.

## Response headers and usage

| Header | Meaning |
| --- | --- |
| `Content-Type` | JSON application response |
| `Cache-Control: no-store` | Do not cache check responses |
| `X-Request-ID` | Correlation ID for troubleshooting |

The response does not echo the submitted email or API key. Successful checks count toward usage. An error response does not provide a usable classification; do not replace it with a cached or invented success.

Each successful request is a separate check, including repeated checks of the same email. To submit multiple addresses together, use [bulk checks](/docs/api/bulk). Neither endpoint has an idempotency-key contract.

## Connection reuse

For low overhead, use an [SDK](/docs/sdks) or reuse the same REST HTTP client and connection pool. Read the complete response so the connection can be reused. Avoid constructing and closing a transport for each request.

An optional [health warmup](/docs/guides/performance) can prepare the same server-side connection ahead of form submission. It is not required before checking an email.

## Failures

Responses include an `X-Request-ID` header for troubleshooting. Keep that ID with the HTTP status and error code; avoid logging the API key or email body.

See [errors](/docs/errors) for the error format. Do not automatically retry a timed-out check: it may already have completed and counted toward usage.