Постмастер 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.ru под аккаунтом, от лица которого будут выполняться запросы к 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

/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, об использовании этих заголовков можно прочитать здесь. Указывается только совместно с именем домена.

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

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

     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

    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

    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, об использовании этих заголовков можно прочитать здесь. Указывается только совместно с именем домена.

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

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

    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

     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.
Помощь Mail
Обновлено 4 декабря 2024 г.
Была ли эта информация полезной?

Помощь по другим проектам

icon