• Помощь Постмастер
  • Постмастер API

Постмастер API

Статистика в Постмастере записывается и отображается (в том числе передаётся в API) по домену из DKIM-подписи (тег 'd'). Значение заголовка From не учитывается.

Краткое описание

Постмастер API позволяет от имени своего аккаунта делать запросы для получения данных в автоматическом режиме. Для авторизации используется Oauth 2.0. При помощи этого протокола скрипт получает от аккаунта-владельца ограниченные права на выполнение некоторых операций, таких как получение статистики по принадлежащим данному аккаунту доменам. Методы Постмастер API доступны по URL, начинающимся с префикса /ext-api/, и будут подробно описаны ниже.

Авторизация и токены

Для получения доступа к API необходимо сгенерировать два токена:
  • refresh_token — долговременный токен — используется для того, чтобы генерировать кратковременные access_token для доступа к API. Refresh_token не имеет срока действия, может быть сгенерирован снова по желанию владельца аккаунта.
  • access_token — кратковременный токен — используется в каждом сеансе работы с API и передаётся с каждым запросом в HTTP заголовке Bearer. Время жизни access_token — 1 час.

Пошаговая процедура получения токена и выполнения первого запроса к API с иcпользованием curl:

1. Будучи авторизованным на Mail под аккаунтом, от лица которого будут выполняться запросы к API, перейдите по ссылке для получения пары токенов (refresh_token, access_token).

В результате вы получите ответ в формате JSON следующего вида:

{"access_token":"1222362434157c389d38348daf10ff73099cf23037363631",

"expires_in":3600,"refresh_token":"8d94455cb4f473f2a5801749b0f0fbe1099ca23037363831"}

2. Для того чтобы обновить протухший access_token, делаем POST запрос следующего вида (менять нужно только "значение_вашего_токена", конструкция "grant_type=refresh_token" меняться не должна):

curl -X POST "https://o2.mail.ru/token" -d "client_id=postmaster_api_client&grant_type=refresh_token&refresh_token=значение_вашего_токена"

В результате будет получен код 200 и JSON следующего вида:

{"expires_in":3600,"access_token":" 7k232kd232q20zl09085328nm23238nc2mmx279ca908r270'"}

3. Полученный access_token необходимо отправлять в HTTP заголовке  Bearer вместе с каждым запросом к API.

Bearer: 7k232kd232q20zl09085328nm23238nc2mmx279ca908r270

Например, так будет выглядеть запрос к API на получение списка подтверждённых доменов для текущего аккаунта. Запрос выполнен с помощью curl и полученного access_token:

curl -k -X GET "https://postmaster.mail.ru/ext-api/reg-list/" -H 'Bearer: 7k232kd232q20zl09085328nm23238nc2mmx279ca908r270>'

В случае удачи в возвращаемом JSON будет присутствовать "ok": true, например:  {"ok": true, domains: []}

    

Методы API

Команда Описание Параметр

Примеры вызовов с помощью curl и ответов в формате JSON

/ext-api/reg-list/

Выводит список подтверждённых для данного аккаунта доменов. Возвращает пустой список, если нет ни одного подтверждённого домена.

 Дополнительные параметры не используются.

Пример вызова с помощью curl:


curl -k -X GET "https://postmaster.mail.ru/ext-api/reg-list/

"-H 'Bearer: 6c5bf168b3d7852a0bdd66283e744b8099ca2303736'


Ответ в формате JSON:


{"ok": true, "domains":[

{"domain":"alphadomain.ru"},

{"domain":"betadomain.ru"},

{"domain":"gammadomain.ru"}

]}

/ext-api/troubles-list/

Выводит список доменов, у которых в веб-интерфейсе вы видите уведомление о наличии проблем (SPF, DKIM, DMARC).

Дополнительные параметры не используются.

Пример вызова с помощью curl:


curl -k -X GET "https://postmaster.mail.ru/ext-api/troubles-list/"

-H 'Bearer: 6c5bf168b3d7852a0bdd66283e744b8099ca2303736'


Ответ в формате JSON


{ "ok": true,

"data":[

{"domain": "alphadomain.ru","errors": [

 {"msg": "DMARC check failed.", "code": -1},

 {"msg": "DKIM statistics not available", "code": 0}],},

{"domain": "betadomain.ru","errors": [

 {"msg": "DMARC (p=None).", "code": 1}],},

{"domain": "gammadomain.ru","errors": [

 {"msg": "SPF not found.", "code": -2},

 {"msg": "DMARC check failed.", "code": -1}],}

]}

/ext-api/stat-list/

Выводит cуммарную статистику по заданному периоду, домену, тегу. В случае успеха содержит в JSON ответе {ok:"true"}.
  • date_from — обязателен, начальная дата, начиная с которой (включительно) выводится статистика. Задается в виде YYYY-MM-DD (пример: 2018-06-14). Разница между date_from и текущей датой не должна составлять более 1 года.
  • date_to — необязателен, конечная дата, по которую (включительно) выводится статистика. Задается в виде YYYY-MM-DD. Если не указана — берётся текущая дата.
  • domain — имя домена, по которому необходимо вывести статистику. Например, gammadomain.ru. По дефолту статистика выводится по всем подтверждённым доменам.
  • msgtype — имя тега, по которому необходимо вывести статистику. Статистика передаётся по письмам, содержащим данный тег в заголовках X-Mailru-Msgtype/X-Postmaster-Msgtype, об использовании этих заголовков можно прочитать здесь. Указывается только совместно с именем домена.

Пример вызова с помощью curl:


1. Вывод статистики за период с 25.04.2018 по текущие сутки по всем подтверждённым доменам:


curl -k -X GET "https://postmaster.mail.ru/ext-api/stat-list/

?date_from=2018-04-25" -H 'Bearer:

6c5bf168b3d7854a0bdd36283e744b20992a2313736'


Ответ в формате JSON:


{ "ok": true,
"data":[

{ "domain":"alphadomain.ru",

"delivered":2, "messages_sent":0, "deleted_read":1, "spam":0,

"read":2, "spam_percent":0.0, "probably_spam_percent":0.0,

"complaints":0, "deleted_unread":0, "probably_spam":0},

{ "domain":"betadomain.ru",

"delivered":0, "messages_sent":0, "deleted_read":0, "spam":0,

"read":0, "spam_percent":0.0, "probably_spam_percent":0.0,

"complaints":0, "deleted_unread":0, "probably_spam":0},

{ "domain":"gammadomain.ru",

"delivered":19, "messages_sent":29, "deleted_read":0, "spam":10,

"read":22, "spam_percent":0.0, "probably_spam_percent":0.0,

"complaints":0, "deleted_unread":4, "probably_spam":0}

]}


2. Вывод статистики по домену alphadomain.ru за период с 25.04.2018 по 01.05.2018. Вызов с параметрами domain и date_from, date_to:


curl -k -X GET "https://postmaster.mail.ru/ext-api/stat-list/?domain=alphadomain.ru&date_from=

2018-04-25&date_to=2018-05-01" -H 'Bearer: 6c5bf168b3d7854a0bdd36283e744b20992a2313736'


Ответ в формате JSON:


{ "ok": true,
"data": [

{ "domain":"alphadomain.ru",

"delivered":46, "messages_sent":46, "deleted_read":221,

"spam":0, "read":212, "spam_percent":0.0, 

"probably_spam_percent":0.0, "complaints":1, 

"deleted_unread":960, "probably_spam":0}

]}


3. Вывод статистики по домену alphadomain.ru и тегу "hotnews" за выбранный период. Вызов с параметрами domain, date_from, date_to и msgtype:


curl -k -X GET "https://postmaster.mail.ru/ext-api/stat-list/?domain=alphadomain.ru&date_from=

2018-04-25&date_to=2018-05-01&msgtype=hotnews" -H 'Bearer: 6c5bf168b3d7854a0bdd36283e744b20992a2313736'


Ответ в формате JSON:


{ "ok": true,
"data": [

{ "domain":"alphadomain.ru",

"delivered":26, "messages_sent":26, "deleted_read":21,

"spam":0, "read":20, "spam_percent":0.0, "probably_spam_percent":0.0,

"complaints":0, "deleted_unread":12, "probably_spam":0}

]}

/ext-api/stat-list-detailed/

Выводит детальную статистику (разбиение по дням) по заданному периоду, домену, тегу.
  • date_from — обязателен, начальная дата, начиная с которой(включительно) выводится статистика. Задается в виде YYYY-MM-DD (пример: 2018-06-14). Разница между date_from и текущей датой не должна составлять более 1 года.
  • date_to — необязателен, конечная дата, по которую (включительно) выводится статистика. Задается в виде YYYY-MM-DD. Если не указана — берётся текущая дата.
  • domain — имя домена, по которому необходимо вывести статистику. По дефолту статистика выводится по всем подтверждённым доменам.
  • msgtype — имя тега, по которому необходимо вывести статистику. Статистика передаётся по письмам, содержащим данный тег в заголовках X-Mailru-Msgtype/X-Postmaster-Msgtype, об использовании этих заголовков можно прочитать здесь. Указывается только совместно с именем домена.

Пример вызова с помощью curl:


1. Вывод детальной статистики по домену alphadomain.ru за период с 23.04.2018 по 25.04.2018. Вызов с параметрами domain и date_from, date_to:


curl -k -X GET "https://postmaster.mail.ru/ext-api/stat-list-detailed/

?domain=alphadomain.ru&date_from=2018-04-23&date_to=2018-04-25" -H 'Bearer:

6c5bf168b3d7854a0bdd36283e744b20992a2313736'


Ответ в формате JSON:


{ "ok": true,

"data": [

{"domain": "alphadomain.ru","data": [

{"delivered": 4980696, "messages_sent": 4980699,

"deleted_read": 75309, "spam": 0, "read": 327158,"spam_percent": 0,

"date": "2018-04-25", "reputation": 0.0457271469759617,

"complaints": 1877, "deleted_unread": 148685, "probably_spam": 3, "trend": -8.50375076175999,

"probably_spam_percent": 0.00006023250953330045}

{"delivered": 5205823, "messages_sent": 5205828,

"deleted_read": 79964, "spam": 0, "read": 331509, "spam_percent": 0,

"date": "2018-04-24", "reputation": 0.0459325440733408,

"complaints": 1868, "deleted_unread": 169365, "probably_spam": 5, "trend": -7.67667312958405,

"probably_spam_percent": 0.00009604620052756257}

{"delivered": 5043425, "messages_sent": 5043434,

"deleted_read": 91322, "spam": 0, "read": 294812, "spam_percent": 0,

"date": "2018-04-23", "reputation": 0.0452646935881204,

"complaints": 2294, "deleted_unread": 173716, "probably_spam": 9, "trend": -4.854289596974,

"probably_spam_percent": 0.00017844984191326782}

]}


2. Вывод статистики по домену alphadomain.ru и тегу "hotnews" за выбранный период. Вызов с параметрами domain, date_from, date_to и msgtype:


curl -k -X GET "https://postmaster.mail.ru/ext-api/stat-list-detailed/?domain=

alphadomain.ru&date_from=2018-04-23&date_to=2018-04-25&msgtype=hotnews" -H 'Bearer:

6c5bf168b3d7854a0bdd36283e744b20992a2313736'


Ответ в формате JSON:


{ "ok": true,
"data": [

{ "domain": "alphadomain.ru","data": [

{ "delivered": 8143, "messages_sent": 8143,

"deleted_read": 707, "spam": 0, "read": 1152, "spam_percent": 0,

"date": "2018-04-25", "reputation": 0, "complaints": 14,

"deleted_unread": 3094, "probably_spam": 0, "trend": 0,

"probably_spam_percent": 0}

{ "delivered": 10165, "messages_sent": 10165,

"deleted_read": 800, "spam": 0, "read": 1286, "spam_percent": 0,

"date": "2018-04-24", "reputation": 0, "complaints": 4,

"deleted_unread": 3863, "probably_spam": 0, "trend": 0,

"probably_spam_percent": 0}

{"delivered": 9703, "messages_sent": 9703,

"deleted_read": 802, "spam": 0, "read": 1303, "spam_percent": 0,

"date": "2018-04-23", "reputation": 0, "complaints": 6,

"deleted_unread": 3826, "probably_spam": 0, "trend": 0,

"probably_spam_percent": 0}

]}

Лимиты

  • Время жизни access_token – 1 час.
  • Количество запросов для каждой из групп (/ext-api/reg-list/, /ext-api/troubles-list/) и (/ext-api/stat-list/, /ext-api/stat-list/detailed) составляет 10 обращений в минуту по каждому домену с одного аккаунта

Возможные ошибки

  • HTTP status "403 Forbidden" означает проблему в авторизации (например истёк access_token ). В этом случае необходимо получить свежий access_token, используя полученный в refresh_token.
  • Ошибка "Token not found" , вида { "error":"token not found", "error_code":6, "error_description":"token not found"} означает неверно указанный refresh_token.
  • Ошибка "429 Unknown Status Code" вида {"detail": "Запрос был проигнорирован. Expected available in N seconds."} означает, что было превышено количество запросов для одной из групп (/ext-api/reg-list/, /ext-api/troubles-list/) и (/ext-api/stat-list/, /ext-api/stat-list/detailed). 
  • Ошибка в JSON вида { "error": "..." } означает, что произошла ошибка на стороне API (были переданы неверные параметры для запроса, несуществующий домен, отсутствует статистика). Описания ошибок различаются для разных методов API.
  • Ошибка "error": "Wrong param: date_from, older than 1 year" означает, что разница между date_from и текущей датой превышает 1 год.
  • Ошибка "error": "Wrong param: date_from > date_to" означает, что в date_to указана более ранняя дата, чем в date_from.

Обновлено 27 августа 2024 г.
Была ли эта информация полезной?