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

# Email Validation API

> Enhance inbox placement and keep your mailing lists healthy with Cleariflow’s best‑in‑class Email Validation API.

## Quick Start

To make a request, provide your unique `api_key` and the `email` you want to check—nothing else is required:

```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = jane.doe@acme-corp.com
```

The request succeeds and returns all available insights for the address:

<ResponseExample>
  ```json theme={"system"}
  {
    "email": "jane.doe@acme-corp.com",
    "autocorrect": "",
    "deliverability": "DELIVERABLE",
    "quality_score": 0.85,
    "is_valid_format": {
      "value": true,
      "text": "TRUE"
    },
    "is_free_email": {
      "value": false,
      "text": "FALSE"
    },
    "is_disposable_email": {
      "value": false,
      "text": "FALSE"
    },
    "is_role_email": {
      "value": false,
      "text": "FALSE"
    },
    "is_catchall_email": {
      "value": false,
      "text": "FALSE"
    },
    "is_mx_found": {
      "value": true,
      "text": "TRUE"
    },
    "is_smtp_valid": {
      "value": true,
      "text": "TRUE"
    }
  }
  ```
</ResponseExample>

### Request parameters

<ParamField query="api_key" type="string" required>
  Your personal API credential. Keys are scoped per Cleariflow product, so an
  Email Validation key will not authorize requests to, for example, the IP
  Geolocation API.
</ParamField>

<ParamField query="email" type="String" required>
  The email address you want to verify.
</ParamField>

<ParamField query="auto_correct" type="Boolean">
  Optional flag to disable autocorrection. Set `auto_correct=false` to turn it
  off. It is enabled by default.
</ParamField>

### Response parameters

Responses are returned as compact, standardized [JSON](https://www.json.org/json-en.html).

<ResponseField name="email" type="String">
  Echoes the `email` submitted in the request.
</ResponseField>

<ResponseField name="auto_correct" type="String">
  Suggested correction when a likely typo is detected (e.g.,
  [johnsmith@gmial.com](mailto:johnsmith@gmial.com) => [johnsmith@gmail.com](mailto:johnsmith@gmail.com)). Empty if no suggestion.
</ResponseField>

<ResponseField name="deliverability" type="String">
  Cleariflow’s assessment of whether the address can receive mail. Possible
  values: `DELIVERABLE`, `UNDELIVERABLE`, `UNKNOWN`. `DELIVERABLE` requires a
  successful SMTP check; if MX records exist but SMTP cannot confirm the mailbox
  (common with large providers), the result is `UNKNOWN`. All plans run the same
  checks; free plans differ only in monthly quota and rate limits (see error
  codes 422 and 429).
</ResponseField>

<ResponseField name="quality_score" type="Float">
  A decimal score from `0` to `0.99` reflecting address quality. Disposable
  addresses are capped near `0.05`; unverified SMTP results are capped at `0.55`.
</ResponseField>

<ResponseField name="is_valid_format" type="Boolean">
  True when the address matches the standard pattern `local@domain.tld`.
  Missing elements or invalid characters yield `false`.
</ResponseField>

<ResponseField name="is_free_email" type="Boolean">
  True if the domain belongs to a free email provider (e.g., Gmail, Yahoo).
</ResponseField>

<ResponseField name="is_disposable_email" type="Boolean">
  True if the domain is on our list of disposable/temporary inbox providers
  (e.g., Mailinator, Yopmail).
</ResponseField>

<ResponseField name="is_role_email" type="Boolean">
  True if the local part appears to be a role account rather than an
  individual, e.g., `team@`, `sales@`, `info@`.
</ResponseField>

<ResponseField name="is_catchall_email" type="Boolean">
  True if the domain is configured as a
  [catch‑all](https://www.corporatecomm.com/faqs/other-questions/what-is-a-catch-all-account).
</ResponseField>

<ResponseField name="is_mx_found" type="Boolean">
  True when [MX records](https://en.wikipedia.org/wiki/MX_record) exist for the
  domain.
</ResponseField>

<ResponseField name="is_smtp_valid" type="Boolean">
  True if the
  [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol)
  verification succeeds. If SMTP fails but other checks pass, the result may be
  `UNKNOWN`. We advise against blocking signups or form submissions solely on
  SMTP failures.
</ResponseField>

## Request examples

### Example: likely misspelling

This example shows a request where a probable typo is detected in the submitted
address.

Even when a likely misspelling is found, all other checks (e.g., free email,
disposable domain) are performed against the originally submitted address—not
the suggested correction.

```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith@gmial.con
```

A successful response looks like:

```json theme={"system"}
{
  "email": "johnsmith@gmial.con",
  "autocorrect": "johnsmith@gmail.com",
  "deliverability": "UNKNOWN",
  "quality_score": 0.4,
  "is_valid_format": {
    "value": true,
    "text": "TRUE"
  },
  "is_free_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_disposable_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_role_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_catchall_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_mx_found": {
    "value": false,
    "text": "FALSE"
  },
  "is_smtp_valid": {
    "value": false,
    "text": "FALSE"
  }
}
```

### Example: invalid format

This example demonstrates an address that fails basic formatting. When
`is_valid_format` is `false`, subsequent checks (e.g., `is_free_email`,
`is_role_email`) are skipped and reported as `false`.

```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith
```

A successful response looks like:

```json theme={"system"}
{
  "email": "johnsmith",
  "autocorrect": "",
  "deliverability": "UNDELIVERABLE",
  "quality_score": 0.0,
  "is_valid_format": {
    "value": false,
    "text": "FALSE"
  },
  "is_free_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_disposable_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_role_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_catchall_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_mx_found": {
    "value": false,
    "text": "FALSE"
  },
  "is_smtp_valid": {
    "value": false,
    "text": "FALSE"
  }
}
```

## Bulk upload (CSV)

Prefer not to call the API directly? Use the CSV bulk uploader—the results will
be emailed to you once processing finishes.

When uploading a CSV, follow these guidelines:

* Place the email addresses in the first column.
* Delete any blank rows.
* Use one address per row.
* Limit files to a maximum of 50,000 rows.

## Response and error codes

Errors are returned in JSON with a code and human‑readable description. Common
codes are listed below.

| Code | Type                  | Details                                                        |
| ---- | --------------------- | -------------------------------------------------------------- |
| 200  | OK                    | Request completed successfully.                                |
| 400  | Bad request           | Malformed or invalid request.                                  |
| 401  | Unauthorized          | Authentication failed—usually a missing or invalid API key.    |
| 422  | Quota reached         | Quota exhausted (e.g., insufficient credits on free plans).    |
| 429  | Too many requests     | Rate limit exceeded (free plans allow up to 1 request/second). |
| 500  | Internal server error | Unexpected error on our side.                                  |
| 503  | Service unavailable   | Service temporarily unavailable.                               |

## Other notes

Plan note: All plans (free and paid) run the same validation checks, including MX
lookup, SMTP verification, and catch-all detection.

Billing note: Each email evaluated consumes one credit per request—regardless of
outcome. Submitting an invalid address (e.g., "fda3346ds") still counts as one
credit.