> ## 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.
# API проверки email
> Повышайте доставляемость писем и поддерживайте здоровье рассылок с лучшей в своём классе API проверки email от Cleariflow.
## Быстрый старт
Для запроса нужны только ваш уникальный `api_key` и проверяемый `email` — больше ничего не требуется:
```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = jane.doe@acme-corp.com
```
При успехе запрос возвращает все доступные данные об адресе:
```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"
}
}
```
### Параметры запроса
Ваш персональный API-ключ. Ключи привязаны к конкретному продукту Cleariflow, поэтому ключ Email Validation не авторизует запросы, например, к API геолокации IP.
Email-адрес, который нужно проверить.
Необязательный флаг для отключения автокоррекции. Установите `auto_correct=false`, чтобы отключить её. По умолчанию включена.
### Параметры ответа
Ответы возвращаются в компактном стандартизированном формате [JSON](https://www.json.org/json-en.html).
Эхо-значение `email`, переданного в запросе.
Предлагаемая коррекция при обнаружении вероятной опечатки (например, [johnsmith@gmial.com](mailto:johnsmith@gmial.com) => [johnsmith@gmail.com](mailto:johnsmith@gmail.com)). Пусто, если предложений нет.
Оценка Cleariflow о том, может ли адрес получать почту. Возможные значения: `DELIVERABLE`, `UNDELIVERABLE`, `UNKNOWN`. `DELIVERABLE` требует успешной SMTP-проверки; если MX-записи есть, но SMTP не подтвердил ящик (часто у крупных провайдеров), результат `UNKNOWN`. На всех планах выполняются одинаковые проверки; бесплатные отличаются только месячной квотой и лимитом RPS (см. коды ошибок 422 и 429).
Десятичная оценка от `0` до `0.99`, отражающая качество адреса. Disposable-адреса ограничены около `0.05`; без подтверждения SMTP — максимум `0.55`.
`true`, если адрес соответствует стандартному шаблону `local@domain.tld`. Отсутствующие элементы или недопустимые символы дают `false`.
`true`, если домен принадлежит бесплатному почтовому провайдеру (например, Gmail, Yahoo).
`true`, если домен есть в нашем списке одноразовых/временных почтовых сервисов (например, Mailinator, Yopmail).
`true`, если локальная часть выглядит как ролевой аккаунт, а не личный, например `team@`, `sales@`, `info@`.
`true`, если домен настроен как [catch-all](https://www.corporatecomm.com/faqs/other-questions/what-is-a-catch-all-account).
`true`, если для домена существуют [MX-записи](https://en.wikipedia.org/wiki/MX_record).
`true`, если [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol)-проверка прошла успешно. При неудаче SMTP, но успехе других проверок результат может быть `UNKNOWN`. Не рекомендуем блокировать регистрации или отправку форм только из-за ошибок SMTP.
## Примеры запросов
### Пример: вероятная опечатка
Этот пример показывает запрос, в котором обнаружена вероятная опечатка в переданном адресе.
Даже при обнаружении вероятной опечатки все остальные проверки (например, бесплатная почта, одноразовый домен) выполняются для изначально переданного адреса — а не для предложенной коррекции.
```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith@gmial.con
```
Успешный ответ выглядит так:
```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"
}
}
```
### Пример: неверный формат
Этот пример демонстрирует адрес, не прошедший базовую проверку формата. Когда `is_valid_format` равен `false`, последующие проверки (например, `is_free_email`, `is_role_email`) пропускаются и возвращаются как `false`.
```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith
```
Успешный ответ выглядит так:
```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"
}
}
```
## Массовая загрузка (CSV)
Не хотите вызывать API напрямую? Используйте массовую загрузку CSV — результаты будут отправлены на email после завершения обработки.
При загрузке CSV следуйте этим рекомендациям:
* Размещайте email-адреса в первом столбце.
* Удалите пустые строки.
* Используйте один адрес на строку.
* Ограничьте файлы максимум 50 000 строками.
## Коды ответов и ошибок
Ошибки возвращаются в JSON с кодом и понятным описанием. Ниже перечислены распространённые коды.
| Code | Type | Details |
| ---- | --------------------- | ------------------------------------------------------------------------------- |
| 200 | OK | Запрос успешно выполнен. |
| 400 | Bad request | Некорректный или недопустимый запрос. |
| 401 | Unauthorized | Ошибка аутентификации — обычно отсутствует или неверен API-ключ. |
| 422 | Quota reached | Квота исчерпана (например, недостаточно кредитов на бесплатных тарифах). |
| 429 | Too many requests | Превышен лимит частоты запросов (на бесплатных тарифах до 1 запроса в секунду). |
| 500 | Internal server error | Непредвиденная ошибка на нашей стороне. |
| 503 | Service unavailable | Сервис временно недоступен. |
## Прочее
Примечание по тарифам: на всех планах (бесплатных и платных) выполняются одинаковые проверки, включая MX, SMTP и catch-all.
Примечание по биллингу: каждый проверенный email расходует один кредит за запрос — независимо от результата. Отправка невалидного адреса (например, «fda3346ds») всё равно считается за один кредит.