Подробная статистика рассылки

Получить подробную статистику по заданной группе сообщений. Группа формируется по указанному почтовому домену или адресу, идентификатору или дате рассылки. Выводятся данные о статусе сообщений в почтовых ящиках получателей, времени прочтения, социально-демографических характеристиках получателей.

Синтаксис запроса

https://postoffice.yandex.ru/api/1.0/stat-view
 ? oauth_token=<токен>
 & (domain=<домен> | email=<адрес>)
 & [id=<идентификатор рассылки>]
 & [listid=<List-ID>]
 & [year=<год>]
 & [month=<месяц>]
 & [day=<день>]
Query-параметры
oauth_token *

Токен доступа OAuth. Подробнее о процедуре получения токена см. в разделе Авторизация приложения с помощью OAuth-токена.

domain *

Почтовый домен — источник рассылок.

email *

Адрес электронной почты — источник рассылок.

id

Числовой идентификатор рассылки. В качестве идентификатора используется значение поля id в ответе метода stat-list.

listid

Идентификатор рассылки — значение заголовка List-ID.

year

Год рассылки. Значение — четырехзначное число.

month

Месяц рассылки. Допустимые значения: 1-12.

day

День рассылки. Допустимые значения: 1-31.

*  Обязательный параметр

Внимание. В одном запросе можно формировать группировку только по идентификатору рассылки (параметры: id и listid) или только по дате (параметры: year, month и day).

Формат ответа

Возвращает подробные статистические данные по заданной группе рассылок, включающие:

  • информацию о статусе сообщений в почтовых ящиках получателей (прочитано, не прочитано, помечено как спам, удалено);
  • сведения о времени и полноте прочтения сообщений;
  • оценку социально-демографических характеристик получателей (распределение по полу, возрасту, уровню доходов и области интересов).

Общая структура ответа приведена в листинге ниже.

{
  // Общие сведения о запросе.
  "session":"tuiC9Cae",
  "subject":"",
  "total":32881,
  "dkim": { ... }

  // Статус сообщений.
  "spam": { ... },
  "deleted": { ... },
  "read": { ... },
  "not_read": { ... },

  // Сведения о прочтении.
  "scrolling": [ ... ],
  "read_time": [ ... ],
  "till_read_time": [ ... ],
  "read_hour": [ ... ],

  // Социально-демографическая статистика.
  "cr": { ... },
}

Полный формат ответа

{
  // Общие сведения о запросе.
  "session": "tuiC9Cae",
  "subject": "",
  "total":32881,
  "dkim":{
    "pass":26,
    "fail":2,
    "neutral":32853
  },

  // Статус сообщений.
  "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
  },

  // Сведения о прочтении.
  "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
    }
  ],

  // Социально-демографическая статистика.
  "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

Идентификатор сессии, в рамках которой обрабатывался запрос к API. Сообщайте этот идентификатор при обращении в службу поддержки Яндекса по поводу сбоев или ошибок в работе API Почтового офиса.

subject

Тема сообщений, по которым выводится статистика. Если в группу вошли сообщения с различными темами (например, при выводе статистике по дате), в этом поле выводится пустая строка.

total

Общее количество сообщений, вошедших в группу.

dkim

Результаты проверки подписи сообщений по протоколу DKIM.

pass

Количество сообщений, успешно прошедших проверку DKIM-подписи.

fail

Количество сообщений, не прошедших проверку DKIM-подписи.

neutral

Количество сообщений, не имевших DKIM-подписи или прошедших проверку с результатом neutral.

spam

Поле, содержащее статистику по сообщениям, отмеченным как спам пользователями либо автоматически доставленными в папку Спам средствами Спамообороны.

total

Общее количество сообщений, которые были отмечены как спам пользователем или автоматически. Включает сообщения, которые были после этого удалены.

instant

Количество сообщений, доставленных в папку Спам (автоматически определенных как спам средствами Спамообороны).

read

Количество сообщений, отмеченных получателями как спам после прочтения.

not_read

Количество сообщений, которые получатели отметили как спам, не читая.

not_deleted

Количество сообщений, отмеченных как спам (пользователем или автоматически) и не удаленных.

Значение вычисляется аналогично значению поля spam в ответе метода stat-list.

personal

Количество сообщений, отмеченных как спам персональным спам-фильтром Яндекса (данный пользователь ранее отмечал такие сообщения как спам).

deleted

Поле, содержащее статистику по всем удаленным сообщениям.

total

Общее количество сообщений, удаленных получателями.

read

Количество сообщений, удаленных получателями после прочтения.

not_read

Количество сообщений, которые получатели удалили, не читая.

not_spam

Количество удаленных сообщений, определенных как не спам автоматически или помеченных как не спам получателями.

read

Поле, содержащее статистику по всем прочитанным сообщениям.

total

Общее количество сообщений, прочитанных получателями.

inbox

Количество прочитанных сообщений, оставшихся в почтовых ящиках получателей.

Сюда включаются прочитанные сообщения, определенные как не спам автоматически или помеченные как не спам пользователями и не удаленные.

spam

Количество сообщений, отмеченных как спам, прочтенных и не удаленных получателями.

Сюда включаются сообщения, отмеченные как спам получателем или автоматически средствами Спамообороны.

deleted

Количество сообщений, удаленных получателями после прочтения.

Значение совпадает со значением поля deleted.read.

not_read

Поле, содержащее статистику по всем непрочитанным сообщениям.

total

Общее количество сообщений, не прочитанных получателями.

inbox

Количество непрочитанных сообщений, оставшихся в почтовых ящиках получателей.

Сюда включаются непрочитанные сообщения, определенные как не спам автоматически или помеченные как не спам пользователями и не удаленные.

spam

Количество непрочитанных сообщений, отмеченных как спам.

Сюда включаются сообщения, отмеченные как спам получателем или автоматически средствами Спамообороны.

deleted

Количество сообщений, которые получатели удалили, не читая.

Значение совпадает со значением поля deleted.not_read.

scrolling

Доля текста письма, просмотренная получателями.

Доля просмотренного текста вычисляется как процент высоты текста, до которого пользователь пролистал письмо в веб-интерфейсе Яндекс.Почты. Если пользователь открыл письмо, но не пролистывал его, учитывается доля текста, видимая на экране при открытии.

Рассчитывается фактическая высота письма с учетом настроек конкретного пользователя. Результаты группируются в 10 интервалов по 10 процентов в порядке возрастания: 0—10%, 11—20%, ... 91—100%.

Значение — массив из 10 целых чисел, соответствующих 10 интервалам высоты письма. Каждое число обозначает количество пользователей, пролиставших письмо до указанного интервала высоты.

read_time

Время, затраченное получателями на чтение письма.

Временем чтения письма считается время с момента открытия письма до момента выполнения следующего действия (перехода к следующему письму, возвращения в почтовый ящик и т. п.).

Результаты группируются в интервалы по 10 секунд: 0—10 сек, 11—20 сек и т. д.

Значение — массив хэшей, где каждый хэш описывает количество пользователей, для которых время чтения письма попадает в данный интервал времени. Интервалы выводятся в порядке возрастания. Не выводятся интервалы, в которых количество пользователей равно нулю.

sec

Время чтения письма в секундах.

Значение — целое число, верхняя граница десятисекундного интервала.

count

Количество пользователей, для которых время чтения письма попадает в указанный интервал.

till_read_time

Время, прошедшее с момента получения до прочтения письма.

Время рассчитывается в часах с момента доставки письма в почтовый ящик получателя. Моментом прочтения считается момент выставления флага «Прочитано».

Результаты группируются в интервалы по 1 часу. Выводятся значения не более 24 часов. Пользователи, прочитавшие письмо позднее, чем через 24 часа с момента получения, учитываются в последнем интервале (24 часа).

Значение — массив хэшей, где каждый хэш описывает количество пользователей, прочитавших письмо через указанное количество часов после получения. Точное время прочтения округляется в большую сторону. Например, письмо, прочтенное через 30 минут после получения, будет учтено в интервале «1 час».

hour

Время, прошедшее с момента получения письма до прочтения в часах.

Значение — целое число. Допустимые значения: 1-24.

count

Количество пользователей, прочитавших письмо через указанное количество часов после получения.

read_hour

Распределение момента прочтения письма по времени суток.

Результаты группируются в интервалы по 1 часу. Точное время прочтения округляется в меньшую сторону. Например, письмо, прочтенное в 0:30, будет учтено в интервале «0 часов».

Значение — массив хэшей, где каждый хэш описывает количество пользователей, прочитавших письмо в указанное время суток. Помимо количества прочитавших указывает количество пользователей, пометивших удаливших или письмо как спам после прочтения.

hour

Время суток в момент прочтения письма (в часах).

Значение — целое число. Допустимые значения: 0-23.

count

Количество пользователей, прочитавших письмо в данное время суток.

В данное число не включаются пользователи, отметившие письмо как спам или удалившие его после прочтения.

spam

Количество пользователей, отметивших письмо как спам после прочтения в данное время суток.

deleted

Количество пользователей, удаливших письмо после прочтения в данное время суток.

cr

Поле содержит оценку социально-демографических характеристик аудитории рассылки на основании данных, полученных с помощью технологии Крипта.

total

Общее количество получателей рассылки, для которых есть социально-демографические данные, полученные с помощью технологии Крипта.

male

Вероятность, что получатель — мужчина.

Значение — целое число от 0 до 1000000.

female

Вероятность, что получатель — женщина.

Значение — целое число от 0 до 1000000.

age

Оценка распределения аудитории по возрастным группам.

Значение — массив из пяти целых чисел, соответствующих пяти возрастным группам:

  1. меньше 18 лет;
  2. 18—24 года;
  3. 25—34 года;
  4. 35—44 года;
  5. 45 и более лет

Каждое число представляет собой вероятность, что получатель рассылки относится к данной возрастной группе.

Значение — целое число от 0 до 1000000.

tns

Оценка распределения аудитории по уровню дохода.

Используется шкала уровня дохода, применявшаяся в исследовании российской интернет-аудитории TNS Web Index.

Значение — массив из 3 целых чисел, соответствующих трем группам по уровню дохода:

  1. TNS A — душевой доход в семье ниже среднего по региону;
  2. TNS B — душевой доход в семье соответствует среднему по региону;
  3. TNS C — душевой доход в семье выше среднего по региону.

Каждое число представляет собой вероятность, что получатель рассылки относится к данной группе по уровню дохода.

Значение — целое число от 0 до 1000000.

int

Оценка распределения аудитории по сфере интересов.

Значение — массив из 12 целых чисел, соответствующих 12 группам интересов:

  1. Hi-Tech.
  2. Работа.
  3. Учеба.
  4. Дом.
  5. Общество.
  6. Развлечения и отдых.
  7. Культура.
  8. Спорт.
  9. СМИ.
  10. Бизнес.
  11. Авто.
  12. Прочее.

Каждое число представляет собой количество пользователей, отнесенных к данной группе интересов. Каждый пользователь может быть отнесен более чем к одной группе.