# Validate email address

**POST** `/email/2/validation`

This method lets you request validation of a single email address in real-time,
helping you to identify and remove poor-quality emails from your list.

## Authentication

- **APIKeyHeader** — API key passed via the `Authorization` header.
- **Basic** — HTTP basic authentication.
- **IBSSOTokenHeader** — API key passed via the `Authorization` header.
- **OAuth2** — OAuth 2.0 bearer token.

## Request Body

Content type: `application/json`

### Request example

```json
{
  "to": "john.smith@example.com"
}
```

Content type: `application/x-www-form-urlencoded`

### Request example

```json
"curl -s --user user:password https://{base_url}/email/2/validation --data-urlencode 'to=john.smith@example.com'"
```

## Responses

### 200 Successful response

Content type: `application/json`

### Valid email box response

```json
{
  "to": "john.smith@example.com",
  "validMailbox": "true",
  "validSyntax": true,
  "catchAll": false,
  "disposable": false,
  "roleBased": false,
  "risk": "LOW"
}
```

### Invalid email box response

```json
{
  "to": "jane.smith@example.com",
  "validMailbox": "false",
  "validSyntax": true,
  "catchAll": false,
  "disposable": false,
  "roleBased": false,
  "detailedReasons": "known_hardbounce",
  "risk": "HIGH"
}
```

### Mailbox is unknown response

```json
{
  "to": "john.doe@example.org",
  "validMailbox": "unknown",
  "validSyntax": true,
  "catchAll": false,
  "disposable": false,
  "roleBased": false,
  "reason": "INBOX_FULL",
  "detailedReasons": "mailbox_full",
  "risk": "HIGH"
}
```

### 400 Bad request response

Content type: `application/json`

### Bad request

```json
{
  "requestError": {
    "serviceException": {
      "messageId": "BAD_REQUEST",
      "text": "Bad request"
    }
  }
}
```

### 401 Unauthorized

Content type: `application/json`

```json
{
  "requestError": {
    "serviceException": {
      "messageId": "UNAUTHORIZED",
      "text": "Unauthorized"
    }
  }
}
```

### 403 Forbidden

Content type: `application/json`

```json
{
  "requestError": {
    "serviceException": {
      "messageId": "FORBIDDEN",
      "text": "Forbidden"
    }
  }
}
```

### 429 Too Many Requests

Content type: `application/json`

```json
{
  "requestError": {
    "serviceException": {
      "messageId": "TOO_MANY_REQUESTS",
      "text": "Too many requests"
    }
  }
}
```

### 500 Internal Server Error

Content type: `application/json`

```json
{
  "requestError": {
    "serviceException": {
      "messageId": "GENERAL_ERROR",
      "text": "Something went wrong. Please contact support."
    }
  }
}
```

## Schemas

### ValidationReason

Reason is provided when validMailbox status is unknown.
1. INBOX_FULL - The user quota exceeded / The user inbox is full / The user doesn't accept any more requests.
2. UNEXPECTED_FAILURE - The mail Server returned a temporary error.
3. THROTTLED - The mail server is not allowing us momentarily because of too many requests.
4. TIMED_OUT - The mail Server took a longer time to respond / there was a delay in the network.
5. TEMP_REJECTION - Mail server temporarily rejected.
6. UNABLE_TO_CONNECT - Unable to connect to the Mail Server.

### ApiException

- **requestError** (ApiRequestError, optional)
  - **serviceException** (ApiRequestErrorDetails, optional)
    - **messageId** (string, optional) — Identifier of the error.
    - **text** (string, optional) — Detailed error description.
    - **validationErrors** (object, optional) — Validation errors.

### ApiRequestErrorDetails

- **messageId** (string, optional) — Identifier of the error.
- **text** (string, optional) — Detailed error description.
- **validationErrors** (object, optional) — Validation errors.

### ApiRequestError

- **serviceException** (ApiRequestErrorDetails, optional)
  - **messageId** (string, optional) — Identifier of the error.
  - **text** (string, optional) — Detailed error description.
  - **validationErrors** (object, optional) — Validation errors.

### ValidationRequest

Validation request

- **to** (string, required) — The email address to be validated.

### ValidationResponse

Validation response

- **to** (string, required) — The validated email address.
- **validMailbox** (string, required) — Indicates whether email address is valid.
- **validSyntax** (boolean, required) — Indicates whether email address syntax is valid.
- **catchAll** (boolean, required) — Indicates catch all status of email address.
- **didYouMean** (string, optional) — Suggests similar alternate address that may be valid.
- **disposable** (boolean, required) — Indicates whether email address is disposable.
A disposable email address is a temporary address that is often used for short-term purposes and can be discarded after use.
- **roleBased** (boolean, required) — Indicates whether email address is role-based.
A role-based email address is one that is associated with a specific function or group within an organization,
such as marketing@example.org, rather than an individual person.
- **reason** (ValidationReason, optional) — Reason is provided when validMailbox status is unknown.
1. INBOX_FULL - The user quota exceeded / The user inbox is full / The user doesn't accept any more requests.
2. UNEXPECTED_FAILURE - The mail Server returned a temporary error.
3. THROTTLED - The mail server is not allowing us momentarily because of too many requests.
4. TIMED_OUT - The mail Server took a longer time to respond / there was a delay in the network.
5. TEMP_REJECTION - Mail server temporarily rejected.
6. UNABLE_TO_CONNECT - Unable to connect to the Mail Server.
  Possible values: `TIMED_OUT`, `TEMP_REJECTION`, `THROTTLED`, `INBOX_FULL`, `UNABLE_TO_CONNECT`, `UNEXPECTED_FAILURE`
- **risk** (ApiRisk, required) — Indicates the risk status of email addresses.
High-risk addresses have a very high chance of bouncing and potentially damaging the sender's reputation.
Low-risk addresses have a very low chance of bouncing and are less likely to damage the sender's reputation.
  Possible values: `LOW`, `MEDIUM`, `HIGH`, `UNKNOWN`
- **detailedReasons** (string, optional) — This field is provided when the validMailbox status is 'unknown' or 'false',
offering specific explanations for why the email address has been assigned that status.

### ApiException

- **requestError** (ApiRequestError, optional)
  - **serviceException** (ApiRequestErrorDetails, optional)
    - **messageId** (string, optional) — Identifier of the error.
    - **text** (string, optional) — Detailed error description.
    - **validationErrors** (object, optional) — Validation errors.

### ApiRisk

Indicates the risk status of email addresses.
High-risk addresses have a very high chance of bouncing and potentially damaging the sender's reputation.
Low-risk addresses have a very low chance of bouncing and are less likely to damage the sender's reputation.