Summary statistics for mailings

Get a summary of statistics on mailings from the specified mail domain or address. For each mailing, the total number of messages with each status is shown: read, unread, marked as spam, deleted.

Request syntax

https://postoffice.yandex.ru/api/1.0/stat-list
 ? oauth_token=<access token>
 & (domain=<domain> | email=<address>)
 & [group=<grouping type>]
 & [offset=<offset>]
oauth_token *

OAuth access token. For more information about getting a token, see the section Application authorization using an OAuth token.

domain *

The mail domain to use for outputting statistics on mailings.

email *

The email address to use for outputting statistics on mailings.

group

The type of grouping for statistical data in the response. Acceptable values:

  • subject — By message subject.
  • from — By sender.
  • date — By the sent date.
  • listid — By the value of the List-ID header.

If the group parameter is omitted in the request, grouping is performed by date, subject, and sender.

offset

Output results starting from the specified number. The value is an integer.

oauth_token *

OAuth access token. For more information about getting a token, see the section Application authorization using an OAuth token.

domain *

The mail domain to use for outputting statistics on mailings.

email *

The email address to use for outputting statistics on mailings.

group

The type of grouping for statistical data in the response. Acceptable values:

  • subject — By message subject.
  • from — By sender.
  • date — By the sent date.
  • listid — By the value of the List-ID header.

If the group parameter is omitted in the request, grouping is performed by date, subject, and sender.

offset

Output results starting from the specified number. The value is an integer.

*  Required

Response format

Returns statistical data about mailings from the specified domain or address. Aggregated data is returned. The grouping mode is set in the group parameter. 

{
    "session":"peiN4cho",
    "offset":"eof",
    "list": [
        {   
            "subject":"No subject",
            "id":"4568638327583785227",
            "from":"someuser@example.com",
            "year":"2013",
            "month":"11",
            "day":"5",
            "messages":557,
            "read":91,
            "not_read":363,
            "spam":0,
            "deleted":103
        }   
    ]   
}
session

ID of the session in which the API request was processed. Include this ID when contacting the Yandex support service about bugs or errors you encounter with the Post Office API.

offset

The offset for requesting the next page of results. Acceptable values:

  • Integer — Value of the offset for requesting the next page of output.
  • eof — The last page of output (there are no more results).
list

A list of groups containing aggregated statistical information about mailings. The list is paginated, so no more than 20 groups are returned in the results for each request.

The value is an array. Each array item is a hash describing the group. The hash includes those fields that apply to the set type of data grouping. The full list of possible fields is provided below. For all grouping types, the description includes the fields messages, read, not_read, spam, and deleted.

subject

Subject line of messages in the group. Output only when grouping by message subject.

id

ID number of messages in the group. Given as a hash sum calculated based on the sender's domain and the message subject. Output only when grouping by message subject.

The value of the "id" field is used for requesting statistics by message subject using the stat-view method.

from

The sender of the messages in the group; the value of the From field. Output only when grouping by sender.

year

The year the messages in the group were sent. Output only when grouping by date.

month

The month the messages in the group were sent. Acceptable values: 1-12. Output only when grouping by date.

day

The day the messages in the group were sent. Acceptable values: 1-31. Output only when grouping by date.

messages

The total number of messages included in the group.

The value must be equal to the sum of the values in the read, not_read, spam and deleted fields.

read

The number of messages that were read by recipients.

This value does not include messages:

  • Deleted by the recipient.
  • Marked as spam by the recipient.
  • Automatically put in the Spam folder by Spamoborona.
not_read

The number of messages delivered to the Inbox but not read by recipients.

This value does not include messages that were deleted or marked as spam.

spam

The number of messages that were marked as spam, either manually by the user or automatically by Spamoborona. This value includes both read and unread messages.

This value does not include messages that were deleted by the user (even if they were first marked as spam).

deleted

The number of messages that were deleted by recipients. This value includes both read and unread messages.

This value does not include messages that were marked as spam.