Detailed statistics for a mailing

Get detailed statistics for a set group of messages. The group is formed for a specified mail domain or address, ID, or mailing date. Data is output on the status of messages in recipients' mailboxes, the time when the message was read, and the socio-demographic characteristics of recipients.

Request syntax

https://postoffice.yandex.ru/api/1.0/stat-view
 ? oauth_token=<access token>
 & (domain=<domain> | email=<address>)
 & [id=<mailing ID>]
 & [listid=<List-ID>]
 & [year=<year>]
 & [month=<month>]
 & [day=<day>]
Query parameters
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 that is the source for mailings.

email *

The email address that is the source for mailings.

id

ID number of the mailing. The value of the id field in the response for the stat-list method is used as the ID.

listid

Mailing ID; the value of the List-ID header.

year

Year of the mailing. The value is a four-digit number.

month

Month of the mailing. Acceptable values: 1-12.

day

Day of the mailing. Acceptable values: 1-31.

*  Required

Attention. In a single request, grouping can be formed by only the mailing ID (parameters: id and listid) or only by date (parameters: year, month, and day).

Response format

Returns detailed statistical data for a specified group of mailings, including:

  • Information about the status of messages in recipients' mailboxes (read, unread, marked as spam, deleted).
  • Data on when messages were read, and how much was read.
  • Assessment of the socio-demographic characteristics of recipients (distribution by gender, age, income level, and areas of interest).

The overall structure of the response is shown below.

{
    "session":"tuiC9Cae",
    "subject":"",
    "total":32881,
    "spam": { ... },
    "deleted": { ... },
    "read": { ... },
    "not_read": { ... },
    "scrolling": [ ... ],
    "read_time": [ ... ],
    "till_read_time": [ ... ],
    "read_hour": [ ... ],
    "cr": { ... },
    "dkim": { ... }
}

Detailed response format

{
  // General response information.
  "session": "tuiC9Cae",
  "subject": "",
  "total":32881,
  "dkim":{
    "pass":26,
    "fail":2,
    "neutral":32853
  },

  // Message status.
  "spam": {
    "total":117,
    "instant":16,
    "read":24,
    "not_read":19,
    "not_deleted":117,
    "personal":58
  },
  "deleted": {
    "total":6284,
    "read":2726,
    "not_read":3558,
    "not_spam":6277
  },
  "read": {
    "total":13932,
    "inbox":11179,
    "spam":27,
    "deleted":2726
  },
  "not_read": {
    "total":18949,
    "inbox":15308,
    "spam":83,
    "deleted":3558
  },

  // Information about reading.
  "scrolling": [4, 3, 5, 7, 15, 12, 23, 48, 58, 7464],
  "read_time": [
    {
      "sec":10,
      "count":6169
    },
    {
      "sec":20,
      "count":564
    },
    // ...
    {
      "sec":86110,
      "count":1
    },
    {
      "sec":86400,
      "count":2
    } 
  ],
  "till_read_time": [
    {
      "hour":1,
      "count":1625
    },
    {
      "hour":2,
      "count":213
    },
    // ...
    {
      "hour":23,
      "count":24
    },
    {
      "hour":24,
      "count":3215
    }
  ],
  "read_hour": [
    {
      "hour":0,
      "count":111,
      "spam":0,
      "deleted":18
    },
    // ...  
    {
      "hour":23,
      "count":150,
      "spam":0,
      "deleted":25
    }
  ],

  // Socio-demographic statistics.
  "cr":{
    "total":7648,
    "male":493144,
    "female":503249,
    "age":[54828, 197787, 334424, 241830, 0],
    "tns":[62841, 495598, 436262],
    "int":[4081, 313, 788, 2298, 1087, 1957, 1773, 3807, 895, 4243, 0, 0],
  }
}
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.

subject

The subject of the messages that statistics are being output for. If the group includes messages with different subjects (for example, when getting statistics by date), this field shows an empty string.

total

The total number of messages included in the group.

dkim

Results of verifying the message signatures with the DKIM protocol.

pass

The number of messages that successfully passed DKIM signature verification.

fail

The number of messages that did not pass DKIM signature verification.

neutral

The number of messages that do not have DKIM signatures or passed verification with the neutral result.

spam

A field containing statistics on messages that were marked as spam by users or automatically delivered to the Spam folder by Spamoborona.

total

The total number of messages that were marked as spam, either manually by users or automatically. Includes messages that were later deleted.

instant

The number of messages that were delivered to the Spam folder (automatically labeled as spam by Spamoborona).

read

The number of messages that were marked as spam by recipients after reading them.

not_read

The number of messages that recipients marked as spam without reading them.

not_deleted

The number of messages that were marked as spam (by users, or automatically) and were not deleted.

The value is calculated the same way as the value of the "spam" field in the response to the "stat-list" method.

personal

The number of messages that were marked as spam by the Yandex personal spam filter (the user marked similar messages as spam earlier).

deleted

A field containing statistics for all deleted messages.

total

The total number of messages that were deleted by recipients.

read

The number of messages that were deleted by recipients after reading them.

not_read

The number of messages that recipients deleted without reading them.

not_spam

The number of deleted messages that were automatically labeled as non-spam or marked as non-spam by recipients.

read

A field containing statistics for all read messages.

total

The total number of messages that were read by recipients.

inbox

The number of read messages that remained in recipients' mailboxes.

This includes read messages that were automatically labeled as non-spam or marked as non-spam by users, as well as messages that were not deleted.

spam

The number of messages that were marked as spam that were read and not deleted by recipients.

This includes messages that were marked as spam either manually by the recipient or automatically by Spamoborona.

deleted

The number of messages that were deleted by recipients after reading them.

The value matches the value of the deleted.read field.

not_read

A field containing statistics for all unread messages.

total

The total number of messages that were not read by recipients.

inbox

The number of unread messages that remained in recipients' mailboxes.

This includes unread messages that were automatically labeled as non-spam or marked as non-spam by users, as well as messages that were not deleted.

spam

The number of unread messages that were marked as spam.

This includes messages that were marked as spam either manually by the recipient or automatically by Spamoborona.

deleted

The number of messages that recipients deleted without reading them.

The value matches the value of the deleted.not_read field.

scrolling

The portion of the message text that was viewed by recipients.

The portion of viewed text is calculated as the percent of the text height that the user scrolled the message to in the Yandex.Mail web interface. If the user opened the message but did not scroll down, it corresponds to the portion of text visible on the screen when opened.

This calculation uses the actual height of the message with adjustments for a particular user's settings. Results are grouped into 10 ranges of 10 percentages in ascending order: 0—10%, 11—20%, ... 91—100%.

The value is an array of 10 integers corresponding to the 10 ranges of message height. Each number indicates the number of users who scrolled through the message to the specified height range.

read_time

Time spent by recipients reading the message.

The reading time is interpreted as the time from the moment the message was opened to the moment of the next action (going to the next message, returning to the Inbox, and so on).

Results are grouped in 10-second intervals. 0—10 seconds, 11—20 seconds, and so on.

The value is an array of hashes, where each hash describes the number of users whose reading time falls within the specified time interval. The intervals are output in ascending order. Intervals that have zero users are not output.

sec

The message reading time, in seconds.

The value is an integer representing the upper limit of a ten-second interval.

count

The number of users whose time spent reading the message falls within the specified interval.

till_read_time

The time that passed between the message being received and being read.

The time is calculated in hours from the moment the message was delivered to the recipient's mailbox. The time when the message was read is considered the moment when the "Read" status was set.

Results are grouped in one-hour intervals. Values of no more than 24 hours are output. Users that read the message more than 24 hours after receiving it are included in the last interval (24 hours).

The value is an array of hashes, where each hash describes the number of users who read the message the specified number of hours after receiving it. The exact reading time is rounded up. For example, a message that was read 30 minutes after it was received is in the "one hour" interval.

hour

The time that passed between the message being received and being read, in hours.

The value is an integer. Acceptable values: 1-24.

count

The number of users who read the message the specified number of hours after receiving it.

read_hour

Distribution by time of day for the time when the message was read.

Results are grouped in one-hour intervals. The exact time is rounded down. For example, a message read at 0:30 is in the "0 hours" interval.

The value is an array of hashes, where each hash describes the number of users who read the message at the specified time of day. Besides the number of readers, it shows the number of users who deleted the message or marked it as spam after reading it.

hour

The time of day when the message was read (in hours).

The value is an integer. Acceptable values: 0-23.

count

The number of users who read the message at this time of day.

This number does not include users who marked the message as spam or deleted it after reading it.

spam

The number of users who marked the message as spam after reading it at the specified time of day.

deleted

The number of users who deleted the message after reading it at the specified time of day.

cr

This field contains an estimate of the socio-demographic characteristics of the mailing's audience based on data obtained using Crypta technology.

total

The total number of mailing recipients for which there is socio-demographic data obtained using Crypta technology.

male

The probability that a recipient is male.

The value is an integer from 0 to 1000000.

female

The probability that a recipient is female.

The value is an integer from 0 to 1000000.

age

The estimated distribution of the audience by age groups.

The value is an array of five integers corresponding to five age groups:

  1. under 18
  2. 18—24
  3. 25—34
  4. 35—44
  5. 45 and over

Each number indicates the probability that a mailing recipient is in one of these age groups.

The value is an integer from 0 to 1000000.

tns

The estimated distribution of the audience by income level.

It uses the TNS Web Index income level scale, which is used for research on the Russian internet audience.

The value is an array of three integers corresponding to three income level groups:

  1. TNS A — Per capita income in the family is lower than average for the region.
  2. TNS B — Per capita income in the family matches the average for the region.
  3. TNS C — Per capita income in the family is higher than average for the region.

Each number indicates the probability that a mailing recipient is in one of these income level groups.

The value is an integer from 0 to 1000000.

int

The estimated distribution of the audience by area of interest.

The value is an array of 12 integers corresponding to 12 interest groups:

  1. Hi-Tech.
  2. Work.
  3. Studies.
  4. Home.
  5. Society.
  6. Entertainment and recreation.
  7. Culture.
  8. Sports.
  9. Mass media.
  10. Business.
  11. Auto.
  12. Other.

Each number represents the number of users for the specified interest group. Each user may be assigned to more than one group.