• Помощь Postmaster
  • Postmaster API

Postmaster API

Postmaster statistics is collected and displayed (including API) for DKIM-domain (this domain is used in 'd' tag in DKIM-Signature). The domain from the "From" field does not matter.

Short description

API allows you to automate data collection from the service Postmaster. Oauth 2.0 is used for authorization. As per Oauth 2.0 specification, authorization to access user (resource owner) data can be obtained:
  • limited access to domain statitstics and functions
All methods provided below contain «/ext-api/» in url.

Tokens & Authorization

Authorization requires 2 tokens to be generated:
  • refresh_token — permanent token — it is used to generate access token (short-term) to access the API. Refresh token is persistent and does not have validity interval. It may be generated by the account owner again at any time.
  • access_token — short-term token — immediately provides an access token to work directly with API methods. It must be specified in "Bearer" HTTP-header of every request. The validity interval of acess token is 1 hour.

Step by step guide using curl:

1. After you've signed in to your Mail account from which you will use API, follow the link for generating refresh and access tokens. 

If request succeded, you will get the following JSON in response:

{"access_token":"1222362434157c389d38348daf10ff73099cf23037363631",

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

2. In order to refresh access_token, make POST request of type (change only construction "value_of_your_token", but not "grant_type=refresh_token"):

curl -X POST "https://o2.mail.ru/token" -d "client_id=postmaster_api_client&grant_type=

refresh_token&refresh_token=value_of_your_token"

200 OK HTTP code should be in response with JSON of following type:

{"expires_in":3600,"access_token":" 8d94455cb4f473f2a5801749b0f0fbe1099ca23037363831'"}

3. Access_token you recieve in response should be added to each API request (in the HTTP-header Bearer).

Bearer: 8d94455cb4f473f2a5801749b0f0fbe1099ca23037363831

Here’s an example request to get list of confirmed domains for current account (with access_token ). We used cURL and receved access_token:

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

Success request: 

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



API methods

Request Description Parameters

Examples of requests with curl and JSON responses

/ext-api/reg-list/

List all the confirmed domains for the account. Will return empty list if no domain is.

 No parameters allowed.

Below is example with curl:


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

"-H 'Bearer: 6c5bf168b3d7852a0bdd66283e744b8099ca2303736'


JSON response:


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

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

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

{"domain":"gammadomain.ru"}

]}

/ext-api/troubles-list/

List all the domains which have any problems (SPF, DKIM, DMARC).

No parameters allowed.

Example with curl:


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

-H 'Bearer: 6c5bf168b3d7852a0bdd66283e744b8099ca2303736'


JSON response:


{ "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/

Returns aggregated statistics for domain, timeframe and tag. Whether request was passed succesfully, will return JSON {ok:"true"}.
  • date_from — (mandatory) — timeframe start date. YYYY-MM-DD format (e.g. 2018-06-14). The difference between the  date_from and the current date must not be more than a year.
  • date_to — timeframe end date. YYYY-MM-DD format. If not specified, the current date is used.
  • domain — domain name statistics relates to. E.g. gammadomain.ru. Whether the domain parameter is not used , statistics for all domains will be returned.
  • msgtype — it is a tag to select statistics for specified message class or specific mailing. Message class or mailing can be identified by adding X-Mailru-Msgtype/X-Postmaster-Msgtype headers to messages sent to Mail. Used with domain name only.

Examples with curl:


1. Aggregated statistics for all confirmed domains in timeframe from 25.04.2018 to current day:


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

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

6c5bf168b3d7854a0bdd36283e744b20992a2313736'


JSON response:


{ "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. Aggregated statistics for alphadomain.ru in timeframe from 25.04.2018 to 01.05.2018. Domain, date_from, date_to parameters are used:


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 response:


{ "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. Example of querying statistics for domain aphadomain.ru with "hotnews" tag with timeframe. Domain, date_from, date_to, msgtype parameters are used:


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 response:


{ "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/

Returns detailed statistics (by day) for domain, timeframe and tag. Whether request was passed succesfully, will return JSON {ok:"true"}.
  • date_from — (mandatory) — timeframe start date. YYYY-MM-DD format (e.g. 2018-06-14). The difference between the  date_from and the current date must not be more than a year.
  • date_to — timeframe end date. YYYY-MM-DD format. If not specified, the current date is used.
  • domain — domain name statistics relates to. E.g. gammadomain.ru. Whether the domain parameter is not used , statistics for all domains will be returned.
  • msgtype — it is a tag to select statistics for specified message class or specific mailing. Message class or mailing can be identified by adding X-Mailru-Msgtype/X-Postmaster-Msgtype headers to messages sent to Mail. Used with domain name only.

Examples with curl:

1. Example of request to get detailed statistics for alphadomain.ru in timeframe from 23.04.2018 to 25.04.2018. Domain, date_from, date_to parameters are used:


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 response:


{ "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. Detailed statistics for alphadomain.ru with "hotnews" tag with timeframe. Domain, date_from, date_to, msgtype parameters are used:


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 response:


{ "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}

]}

Limitations

  • The validity interval of acess token - 1 hour.
  • We have individual limits for groups of requests ( (/ext-api/reg-list/, /ext-api/troubles-list/) и (/ext-api/stat-list/, /ext-api/stat-list/detailed) The limit is 10 requests per minute for each domain from the account.

Errors

  • HTTP status "403 Forbidden" implies on authorization error (access_token expired). Make sure you you make request for valid access_token to be granted, use refresh_token. 
  • The error "Token not found" { "error":"token not found", "error_code":6, "error_description":"token not found"} implies that refresh_token is invalid.
  • The error "429 Unknown Status Code" {"detail": "Запрос был проигнорирован. Expected available in N seconds."} implies that the number of requests has been exceeded for one of the groups ((/ext-api/reg-list/, /ext-api/troubles-list/) and (/ext-api/stat-list/, /ext-api/stat-list/detailed)).
  • The type of JSON { "error": "..." } points to API side issue (wrong request methods, invalid domain, missing statistics). Error description vary for different API URIs.
  • The error: "Wrong param: date_from, older than 1 year" implies that the difference between the  date_from and the current date is more than a year.
  • The error: "Wrong param: date_from > date_to" implies that the date_to is earlier than the date_from.

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