Основные понятия и термины
Батч — совокупность email-адресов (индексируется в базе id-шником)
Чанк — часть батча (из чанков слкадывается батч, по кажому отправленному батчу приходит webhook)
Сервис — mailvalidator.ru (в дальнейшем Mailvalidator)

Отправить батч на проверку сервису
Выполняется с помощью POST- запроса.

Пример на Python
Запрос
r = requests.post('https://mailvalidator.ru/api/v2/batch/', json=(payload), headers={'Authorization': 'Token 3fd8b6d08f4339d2d6e3bf415e3bfc7a4a82b37e'})
Ответ
{"Batch_id": 298}
Статусы
где payload в формате
'{"dadgf4gv@mail.ru": "E", "bakalachov@mail.ru": "F", ...}'
Пример на Curl
curl -X POST "https://mailvalidator.ru/api/v2/batch/" -i -H "Authorization: Token ecc28229e2cd7e4532f8e356de32dfd7e8a5b44b" -H "Content-type: application/json" -d '{"aaaa22@mail.ru": "F", "afogu@rambler.ru": "F", "agro-k@mail.ru": "E"}' 
«E» - экспресс-проверка
«F» - полная (дополнительная проверка)

Если Вы подписаны на Webhook от сервиса, то на эндпойнт придут POST-запросы, сразу же после экспресс-проверки.
Для подписки на Webhook обратитесь к вашему менеджеру
Пример

Краткая сводка по батчу
{'data': {'batch_id': 297,
          'email_class_counts': {'A': 0,
                                 'B': 3,
                                 'C': 0,
                                 'F': 3,
                                 'X': 28},
          'mails_count': 34},
 'hook': 'batch.proceeded_short_info'}
Результаты экспресс-проверки
{'data': {'batch_id': 297,
          'emails': {'bakalachov0@mail.ru': 'X',
                     'bakalachov6@mail.ru': 'X',
                     'bdui@aaanet.ru': 'X',
                     'brabotyaga80@list.ru': 'X',
                     'dadgf4gv@mail.ru': 'X'}},
 'hook': 'batch.proceeded_express'}
После того, как на сервисе будет завершена полная проверка на эндпойнт придет POST- запрос
{'data': {'batch_id': 295,
          'emails': {'alendeev.pavel@inbox.ru': 'B',
                     'dizel-torg@bk.ru': 'OK',
                     'info@anti-bankir.ru': 'OK',
                     'info@resurs21.ru': 'OK',
                     'veneramore75@mail.ru': 'OK'}},
 'hook': 'batch.proceeded_full'}
Webhook делает 5 попыток с перерывом в 3 минуты если с Вашей стороны получена ошибка >= 500

Получить статус батча по ID
Выполняется с помощью GET-запроса

Пример на Python
Запрос
r = requests.get('https://mailvalidator.ru/api/v2/batch/296/status/', headers={'Authorization': 'Token 3fd8b6d08f4339d2d6e3bf415e3bfc7a4a82b37e'})
Ответ
{"Full check satus": true, "Express check status": true}
Пример на Curl
curl -X GET "https://mailvalidator.ru/api/v2/batch/9/status/" -i -H "Authorization: Token ecc28229e2cd7e4532f8e356de32dfd7e8a5b44b"

Получить результаты батча по ID
Выполняется с помощью GET-запроса

Пример на Python
Запрос
r = requests.get('https://mailvalidator.ru/api/v2/batch/295/results?check_type=full&email_type=X', headers={'Authorization': 'Token 3fd8b6d08f4339d2d6e3bf415e3bfc7a4a82b37e'})
Ответ
{'emails': {'aaaa22@mail.ru': 'B',
            'akaa2alachov@0815.ru': 'T',
            'akalachov@0815.ru': 'T',
            'akalachov@mail.ru': 'X',
            'gordon_fm@mail.ru': 'X',
            'mihail.net@mailinator.com': 'X',
            'xpert@mail.ru': 'A'}}
Пример на Curl
curl -X GET "https://mailvalidator.ru/api/v2/batch/9/results/?check_type=express&email_type=B" -i -H "Authorization: Token ecc28229e2cd7e4532f8e356de32dfd7e8a5b44b"
Фильтровать можно по check_type[express, full, all] и email_type[A, B, X, OK, T] — допустимые параметры фильтра

Если статус не указан, то возвращает полную статистику, которая готова к данному моменту времени


Получить ID батчей пользователя
Выполняется с помощью GET- запроса

Пример на Python

Запрос
r = requests.get('https://mailvalidator.ru/api/v2/batch?data_since=2017-10-10&data_afte=2049-10- 10&status=processed', headers={'Authorization': 'Token 3fd8b6d08f4339d2d6e3bf415e3bfc7a4a82b37e'})
Ответ
{"Processed": [297, 295, 294, 40, 39, 38, 37, 36, 35, 34, 33, 32, 31, 30, 29, 28, 27, 26]}
Пример на Curl

curl -X GET "https://mailvalidator.ru/api/v2/batch/9/results/?data_since=2017-10-10&data_afte=2049-10-10&status=processed" -i -H "Authorization: Token ecc28229e2cd7e4532f8e356de32dfd7e8a5b44b"
Фильтровать можно по датам и status[processing, processed, all ] — допустимые параметры фильтра


GET — запросы
Отобразить все списки загруженные пользователем(партнером)

Python
r = requests.get('https://mailvalidator.ru/api/v1/maillists/', headers={'Authorization': 'Token 4334635eb14dtt2432d6fa1017113174f2b6e854'})
Отобразить список с id = 9063

Python
r = requests.get('https://mailvalidator.ru/api/v1/maillists/9063/', headers={'Authorization': 'Token 4334635eb14dtt2432d6fa1017113174f2b6e854'})
Скачать результаты ЭКСПРЕСС-проверки (после оплаты)

Python
r = requests.get('https://mailvalidator.ru/api/v1/maillists/results/express/9063/', headers={'Authorization': 'Token 4334635eb14dtt2432d6fa1017113174f2b6e854'})
Результаты находятся в теле ответа, поэтому что бы их скачать, результаты необходимо записать на диск

Python
with open('result_express.zip', 'wb') as f:
  for chunk in r.iter_content():
    f.write(chunk)
Если выполнить данный запрос в строке браузера — архив автоматически скачается
Скачать результаты ПОЛНОЙ проверки (после оплаты)

Python
r = requests.get('https://mailvalidator.ru/api/v1/maillists/results/full/9063/', headers={'Authorization': 'Token 4334635eb14dtt2432d6fa1017113174f2b6e854'})

with open('result_full.zip', 'wb') as f:
  for chunk in r.iter_content():
    f.write(chunk)
Если выполнить данный запрос в строке браузера — архив автоматически скачается
Оплата ЭКСПРЕСС-проверки списка с id=9063

Python
requests.get('https://mailvalidator.ru/api/v1/maillists/pay/express/9063/', headers={'Authorization': 'Token a085f1471b9540b16fe7ded7b5cfa54ab5a978f4'})
Поэтому запросу будет происходить редирект на страницу в личный кабинет для последующей оплаты
Оплата ПОЛНОЙ-проверки списка с id=9063

Python
requests.get('https://mailvalidator.ru/api/v1/maillists/pay/full/9063/', headers={'Authorization': 'Token a085f1471b9540b16fe7ded7b5cfa54ab5a978f4'})
Поэтому запросу будет происходить редирект на страницу в личный кабинет для последующей оплаты

POST — запросы
Загрузить список на проверку

Python
files = {'upload_file': open('/home/kalach/Downloads/TXT/150.txt','rb')}
где 150.txt — файл на проверку

Python
r = requests.post('https://mailvalidator.ru/api/v1/maillists/', files=files, headers={'Authorization': 'Token 4334635eb14dtt2432d6fa1017113174f2b6e854'})
При успешной загрузке списка в ответе (r.text) будет id загруженного списка

Python
{"maillist_id": 9091}

Единичная проверка почтового ящика
Python
r = requests.post('https://mailvalidator.ru/api/v2/email_check/?email=admin@yandex.ru', headers={'Authorization': 'Token 1cdffead9d37d585516050b786b98535cbd26e77'})
Curl
curl -X POST "https://mailvalidator.ru/api/v2/email_check/?email=admin@yandex.ru" -i -H "Authorization: Token 1cdffead9d37d585516050b786b98535cbd26e77"
Возможные ошибки
Статусы