К API-токенам
API Reference

Документация API

Интегрируйте проверку email в ваши приложения через REST API.

Base URL
https://api.mails.expert
Auth
Bearer token
Endpoints
Single verify + bulk jobs
Аутентификация

Все запросы к API требуют Bearer-токен в заголовке Authorization. Можно использовать JWT (из логина) или API-токен (созданный в панели).

Проверка одного email

Проверить один email-адрес. Стоимость: 1 токен.

Массовая проверка email

Отправьте список email для проверки. Стоимость: 1 токен за email.

npm package

Используйте пакет mails.expert для более быстрой интеграции

Если вам удобнее интегрироваться через npm package, а не собирать raw HTTP requests вручную, используйте community package для mails.expert и начинайте с более чистого integration setup.

Установка пакета
npm install @d2sutils/mails-expert

Откройте страницу пакета в новой вкладке, чтобы посмотреть usage, версии и детали установки.

Аутентификация

Все запросы к API требуют Bearer-токен в заголовке Authorization. Можно использовать JWT (из логина) или API-токен (созданный в панели).

Authorization: Bearer YOUR_TOKEN

API-токены начинаются с префикса mv_.

Проверка одного email

Проверить один email-адрес. Стоимость: 1 токен.

Запрос
POST /v1/verify
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "email": "test@example.com"
}
Ответ
{
  "email": "test@example.com",
  "result": "valid",
  "checks": {
    "format": true,
    "domainExists": true,
    "hasMx": true,
    "domainReachable": true,
    "smtpStatus": "valid",
    "isDisposable": false,
    "isRole": false,
    "isBlacklisted": false,
    "isKnownProvider": true,
    "isCatchAll": false
  },
  "reason": "250 2.1.5 OK"
}

Массовая проверка email

Отправьте список email для проверки. Стоимость: 1 токен за email.

1. Отправить email
POST /v1/bulk-verify
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "info@company.com"
  ]
}

// Response:
{
  "jobId": "abc-123",
  "queued": 3
}
2. Проверить прогресс
GET /v1/bulk-verify/abc-123/progress
Authorization: Bearer YOUR_TOKEN

// Response:
{
  "job_id": "abc-123",
  "status": "processing",
  "total": 3,
  "processed": 2,
  "progress_percent": 66
}
3. Получить результаты
GET /v1/bulk-verify/abc-123
Authorization: Bearer YOUR_TOKEN

// Response:
{
  "id": "abc-123",
  "status": "completed",
  "total": 3,
  "processed": 3,
  "results": [
    { "email": "user1@example.com", "result": "valid" },
    { "email": "user2@example.com", "result": "invalid" },
    { "email": "info@company.com", "result": "catch_all" }
  ]
}

Типы результатов

  • valid — Email доставляемый
  • invalid — Email не существует или недоставляемый
  • risky — Email существует, но одноразовый, ролевой или в чёрном списке
  • catch_all — Домен принимает любые email (catch-all сервер)
  • unknown — Не удалось определить доставляемость

Поля проверок

Каждый ответ включает детальные результаты проверок:

format        — Email format is valid
domainExists  — Domain exists (DNS resolves)
hasMx         — Domain has MX records
domainReachable — Domain web server responds
smtpStatus    — SMTP RCPT TO result: valid / invalid / unknown
isDisposable  — Temporary/disposable email provider
isRole        — Role-based address (admin@, info@, support@...)
isBlacklisted — Found on spam blacklists
isKnownProvider — Known trusted provider (Gmail, Yahoo, etc.)
isCatchAll    — Domain accepts all addresses (catch-all)

Примеры cURL

Single verify
curl -X POST https://api.mails.expert/v1/verify \
  -H "Authorization: Bearer mv_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'
Bulk verify
curl -X POST https://api.mails.expert/v1/bulk-verify \
  -H "Authorization: Bearer mv_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["a@example.com", "b@example.com"]}'

Лимиты запросов

API-запросы ограничены по количеству на пользователя. При превышении лимита вы получите код 429. Свяжитесь с поддержкой для увеличения лимитов.

Коды ошибок

  • 401 — Неверный или отсутствующий токен аутентификации
  • 402 — Недостаточно токенов (купите кредиты)
  • 429 — Превышен лимит запросов
  • 500 — Внутренняя ошибка сервера