> ## 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`, якщо домен належить безкоштовному email-провайдеру (наприклад, 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.
## Приклади запитів
### Приклад: ймовірна помилка в написанні
Цей приклад демонструє запит, у якому виявлено ймовірну помилку в переданій
адресі.
Навіть якщо знайдено ймовірну помилку, усі інші перевірки (наприклад, безкоштовний email,
одноразовий домен) виконуються для оригінально переданої адреси — а не
для запропонованої корекції.
```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») все одно зараховується як один
кредит.