Статистика сообщений

messages:list

Отображает список отправленных сообщений.

POST https://api.pushwoosh.com/api/v2/messages:list

Заголовки

Имя	Обязательный	Описание
`Authorization`	Да	Токен серверного API. Должен быть предоставлен в следующем формате: `Authorization: Api <Server Key>`.

Параметры тела запроса

Имя	Обязательный	Тип	Описание
`platforms`	Нет	Array	Платформы сообщений. Возможные значения: `"IOS"`, `"ANDROID"`, `"OSX"`, `"WINDOWS"`, `"AMAZON"`, `"SAFARI"`, `"CHROME"`, `"FIREFOX"`, `"IE"`, `"EMAIL"`, `"HUAWEI_ANDROID"`, `"SMS"`.
`date_range`	Нет	Object	Отчетный период, фильтруется по дате создания сообщения. `date_from` и `date_to` должны соответствовать формату `YYYY-MM-DD` (например, `"2000-01-01"`); оба дня включаются полностью, поэтому `date_from` и `date_to`, установленные на одну и ту же дату, вернут данные за весь этот день.
`campaign`	Нет	String	Код кампании
`filters`	Да	Object	Фильтры сообщений.
`source`	Нет	String	Источник сообщения. Например: `AB_TEST`, `API`, `AUTO_PUSH`, `CP`, `CSV`, `CUSTOMER_JOURNEY`, `EMAIL_API`, `EMAIL_CP`, `GEO_ZONE`, `PUSH_ON_EVENT`, `RSS`.
`messages_codes`	Нет	Array	Коды сообщений, полученные из ответов API `/createMessage`.
`messages_ids`	Нет	Array	ID сообщений, полученные из истории сообщений
`params`	Нет	Object	Укажите, следует ли показывать детали и метрики сообщения. Установите `with_details: true`, чтобы включить объект `"details"`, и `with_metrics: true`, чтобы включить объект `"metrics"` в ответ.
`application`	Да	String	Код приложения Pushwoosh.
`per_page`	Нет	Integer	Количество результатов на странице, от `1` до `499`. Опустите параметр, чтобы получить размер страницы по умолчанию в 500 результатов; передача `500` или более явным образом будет отклонена с ошибкой `400`.
`page`	Нет	Integer	Номер страницы для пагинации, начиная с нуля. См. ограничение на глубокую пагинацию ниже.

messages:list отклоняет запросы, в которых page × per_page превышает 100000 результатов. Сузьте date_range или используйте меньшее значение per_page, чтобы оставаться в пределах лимита.

total — это точное количество сообщений, соответствующих фильтрам, пока это число не превышает 100000, и останавливается на 100001 выше этого значения — больше, чем эта конечная точка может обработать. Не создавайте цикл пагинации за пределами этого лимита: страницы за его пределами будут отклонены, а не пусты. Чтобы извлечь период, содержащий больше сообщений, сузьте date_range для каждого запроса или используйте асинхронный экспорт, который записывает весь период в один CSV-файл без пагинации.

Пример запроса

{
    "filters": {
      "platforms": [],                  // IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS
      "date_range": {
        "date_from": "string",          // Обязательный формат: 2000-01-01
        "date_to": "string"             // Обязательный формат: 2000-01-01
      },
      "source": "API",                  // AB_TEST, API, AUTO_PUSH, CP, CSV, CUSTOMER_JOURNEY, EMAIL_API, EMAIL_CP, GEO_ZONE, PUSH_ON_EVENT, RSS
      "campaign": "string",             // Код кампании
      "messages_ids": [],               // ID сообщений
      "messages_codes": [],             // Коды сообщений
      "application": "string"           // Код приложения Pushwoosh
    },
    "params": {
      "with_details": true,             // Добавить детали сообщения в ответ (объект "details")
      "with_metrics": true              // Добавить метрики сообщения в ответ (объект "metrics")
    },
    "per_page": 20,                     // <= 499
    "page": 0
}

Коды ответов и примеры

{
  "total": 0,
  "items": [{
    "id": 0,
    "code": "string",
    "created_date": "string",
    "send_date": "string",
    "status": "string",
    "platforms": [],
    "source": "string",
    "push_info": {
      "details": {
        "title": "string",
        "filter_name": "string",
        "filter_code": "string",
        "content": {
          "key": "value"
        },
        "platform_parameters": {
          "android_header": "string",
          "android_root_params": {
            "key": "value"
          },
          "ios_title": "string",
          "ios_subtitle": "string",
          "ios_root_params": {
            "key": "value"
          },
          "chrome_header": "string",
          "chrome_root_params": {
            "key": "value"
          },
          "firefox_header": "string",
          "firefox_root_params": {
            "key": "value"
          },
          "conditions": [               // условия по тегам (см. /developer/api-reference/messages-api/#tag-conditions)
            TAG_CONDITION1,
            TAG_CONDITION2,
            ...,
            TAG_CONDITIONN
          ],
          "conditions_operator": "AND", // логический оператор для массивов условий; возможные значения: AND, OR
          "data": {
            "key": "value"
          }
        },
        "follow_user_timezone": true
      },
      "metrics": [{
        "sends": 0,
        "opens": 0,
        "deliveries": 0,
        "inbox_opens": 0,
        "unshowable_sends": 0,
        "errors": 0,
        "platform": 0
      }]
    },
    "email_info": {
      "details": {
        "template": "string",
        "filter_name": "string",
        "filter_code": "string",
        "subject": {
          "key": "value"
        },
        "from_name": "string",
        "from_email": "string",
        "reply_name": "string",
        "reply_email": "string",
        "follow_user_timezone": true,
        "conditions": [              // условия по тегам (см. Messages-api - tag-conditions)
          TAG_CONDITION1,
          TAG_CONDITION2,
          ...,
          TAG_CONDITIONN
        ],
        "conditions_operator": "AND" // логический оператор для массивов условий; возможные значения: AND, OR
      },
      "metrics": [{
        "sends": 0,
        "opens": 0,
        "deliveries": 0,
        "hard_bounces": 0,
        "soft_bounces": 0,
        "rejects": 0,
        "confirmed_sends": 0,
        "unsubs": 0,
        "complaints": 0,
        "errors": 0
      }]
    }
  }]
}

date_range охватывает более 30 дней:

{
  "error": "exceeded the maximum date interval. Max interval: 30 days"
}

page × per_page превышает лимит глубокой пагинации:

{
  "error": "requested result window is too large, narrow the date range"
}

{
  "error": "account not found"
}

totalsByIntervals

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

POST https://api.pushwoosh.com/api/v2/statistics/messages/totalsByIntervals

Авторизация

Авторизация осуществляется через токен доступа API в заголовке запроса.

Параметры тела запроса

Имя параметра	Тип	Описание	Обязательный
`message_code`	string	Код сообщения, полученный из ответов API `/createMessage`.	Да
`platforms`	[int]	Платформы	Нет

Пример запроса

{
  "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // обязательно. Уникальный идентификатор сообщения
  "platforms": [1, 3, 7, 10, 11, 12]          // опционально. Список кодов платформ
}

Поля ответа

Имя	Тип	Описание
`metrics`	array	Содержит массив метрик сообщения
`timestamp`	string	Время метрики.
`platform`	int	Код платформы (например, iOS, Android).
`sends`	string	Количество отправленных сообщений.
`opens`	string	Количество открытых сообщений.
`deliveries`	string	Количество доставленных сообщений.
`inbox_opens`	string	Количество открытий из папки “Входящие”.
`unshowable_sends`	string	Количество отправленных сообщений, которые не могли быть показаны.
`errors`	string	Количество ошибок.
`conversion`	object	Содержит данные о конверсии
`sends`	string	Общее количество отправленных сообщений.
`opens`	string	Общее количество открытых сообщений.
`events`	array	Массив событий с их статистикой
`name`	string	Название события (например, добавление в корзину).
`hits`	string	Количество хитов.
`conversion`	float	Коэффициент конверсии относительно открытий.
`revenue`	float	Доход (только для событий с атрибутами `__amount` и `__currency`).

Пример ответа

{
  "metrics": [{
    "timestamp": "2024-08-03 15:00:00",  // Временная метка метрик в формате "YYYY-MM-DD HH:MM:SS"
    "platform": 3,                       // Код платформы
    "sends": "55902",                    // Количество отправленных сообщений
    "opens": "382",                      // Количество открытых сообщений
    "deliveries": "22931",               // Количество доставленных сообщений
    "inbox_opens": "0",                  // Количество сообщений, открытых из папки "Входящие"
    "unshowable_sends": "2",             // Количество сообщений, которые не удалось показать
    "errors": "0"                        // Количество возникших ошибок
  }],
  "conversion": {
    "sends": "55902",                    // Общее количество отправленных сообщений
    "opens": "772",                      // Общее количество открытых сообщений
    "events": [{
      "name": "cart_add",                // Название события
      "hits": "96",                      // Количество хитов для события
      "conversion": 0.12,                // Коэффициент конверсии относительно открытий
      "revenue": 0                       // Доход, полученный от события (только для событий с атрибутами amount/currency)
    }]
  }
}

getMessageLog

Отображает подробную информацию об отправленных сообщениях.

POST https://api.pushwoosh.com/api/v2/statistics/getMessageLog

Заголовки

Имя	Обязательный	Описание
`Authorization`	Обязательно	Токен доступа API из панели управления Pushwoosh.

Параметры тела запроса

Имя	Обязательный	Тип	Описание
`message_id`	Нет	Integer	Выбрать события сообщений по ID сообщения, полученному из истории сообщений. Пример: `12345678900`.
`message_code`	Нет	String	Выбрать события сообщений по коду сообщения, полученному из ответов API `/createMessage`. Пример: `"A444-AAABBBCC-00112233"`.
`campaign_code`	Нет	String	Выбрать события сообщений по коду кампании, указанному в полезной нагрузке вашего сообщения. Пример: `"AAAAA-XXXXX"`.
`hwid`	Нет	String or Array	Выбрать события сообщений по HWID (Hardware ID) или массиву HWID.
`date_from`	Обязательно, если не предоставлены `message_id`, `message_code` или `campaign_code`	Datetime	Начальная дата для фильтрации сообщений. Формат: `"YYYY-MM-DD HH:MM:SS"`. Пример: `"2000-01-25 00:00:00"`.
`date_to`	Обязательно, если не предоставлены `message_id`, `message_code` или `campaign_code`	Datetime	Конечная дата для фильтрации сообщений. Формат: `"YYYY-MM-DD HH:MM:SS"`. Пример: `"2000-01-26 00:00:00"`.
`limit`	Нет	Integer	Максимальное количество событий сообщений, возвращаемых в одном ответе. Максимальное значение: `100000`.
`pagination_token`	Нет	String	Токен пагинации, полученный из предыдущего ответа `/getMessageLog`. Используйте его для получения дополнительных результатов.
`user_id`	Нет	String	Выбрать события сообщений по пользовательскому User ID. См. `/registerUser` для получения дополнительной информации.
`application_code`	Да	String	Выбрать события сообщений по коду приложения Pushwoosh
`actions`	Нет	Array	Фильтровать результаты по определенным действиям с сообщениями. Возможные значения: `"sent"`, `"delivered"`, `"opened"`, `"inbox_delivered"`, `"inbox_read"`, `"inbox_opened"`, `"inbox_deleted"`.
`platforms`	Нет	Array	Массив целевых платформ для фильтрации результатов. Возможные значения: `"ios"`, `"android"`, `"osx"`, `"windows"`, `"amazon"`, `"safari"`, `"chrome"`, `"firefox"`, `"ie"`, `"email"`, `"huawei_android"`.

Пример запроса

curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/getMessageLog' \
--header 'Authorization: Key API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
   "pagination_token": "PAGINATION_TOKEN_FROM_PREVIOUS_RESPONSE",  // опционально, токен для пагинации
   "limit": 1000,                                  // опционально, максимальное количество записей в одном ответе
   "application_code": "XXXXX-XXXXX",              // код приложения Pushwoosh
   "message_code": "A444-AAABBBCC-00112233",       // опционально, код сообщения, полученный из запроса /createMessaage
   "message_id": 1234567890,                       // опционально, ID сообщения, полученный из панели управления Pushwoosh
   "campaign_code": "AAAAA-XXXXX",                 // опционально, код кампании для получения лога
   "hwid": "aaazzzqqqqxxx",                        // опционально, аппаратный ID конкретного устройства, на которое было отправлено сообщение
   "user_id": "user_123",                          // опционально, ID пользователя, на которого было отправлено сообщение
   "date_from": "2000-01-25 00:00:00",             // опционально, начало периода статистики
   "date_to": "2000-02-10 23:59:59",               // опционально, конец периода статистики
   "actions": ["opened", "inbox_opened"],          // опционально, используется для фильтрации результатов. Возможные значения: "sent", "opened", "delivered", "inbox_delivered", "inbox_read", "inbox_opened", "inbox_deleted". Ответ будет включать все сообщения с указанным(и) действием(ями).
   "platforms": ["ios", "chrome"]                  // опционально, используется для фильтрации результатов. Возможные значения: "ios", "android", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "huawei android"
}'

Коды ответов и примеры

{
  "pagination_token": "PAGINATION_TOKEN_FOR_NEXT_REQUEST",
  "data": [{
    "timestamp": "2000-01-25T11:18:47Z",
    "application_code": "XXXXX-XXXXX",
    "message_id": 12345678900,
    "message_code": "A444-AAABBBCC-00112233",
    "campaign_code": "AAAAA-XXXXX",
    "hwid": "aaazzzqqqqxxx",
    "user_id": "user_123",
    "platform": "android",
    "action": "sent",
    "status": "success",
    "push_alerts_enabled": "true"
  }, {
    "timestamp": "2000-01-25T11:18:49Z",
    "application_code": "XXXXX-XXXXX",
    "message_id": 12345678900,
    "message_code": "A444-AAABBBCC-00112233",
    "campaign_code": "AAAAA-XXXXX",
    "hwid": "aaazzzqqqqxxx",
    "user_id": "user_123",
    "platform": "android",
    "action": "delivered",
    "push_alerts_enabled": "true"
  }, {
    "timestamp": "2000-01-25T11:19:23Z",
    "application_code": "XXXXX-XXXXX",
    "message_id": 12345678900,
    "message_code": "A444-AAABBBCC-00112233",
    "campaign_code": "AAAAA-XXXXX",
    "hwid": "aaazzzqqqqxxx",
    "user_id": "user_123",
    "platform": "android",
    "action": "opened",
    "push_alerts_enabled": "true"
  }]
}

{
  "error": "exceeded the maximum date interval. Max interval: 30 days"
}

{
  "error": "account not found"
}

Статистика Email

linksInteractions

Отображает статистику по кликам на ссылки в email-сообщениях

POST https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractions

Заголовки

Имя	Обязательный	Описание
`Authorization`	Да	Токен доступа API из панели управления Pushwoosh.

Параметры тела запроса

Имя	Обязательный	Тип	Описание
`date_range`	Нет	Object	Определяет отчетный период. Содержит `date_from` и `date_to`.
`filters`	Да	Object	Фильтры email.
`application`	Да	String	Код приложения Pushwoosh (в качестве альтернативы укажите `campaign`, `messages_ids` или `message_codes`).
`messages_codes`	Да	Array	Коды сообщений (в качестве альтернативы укажите `application`, `campaign` или `messages_ids`).
`campaign`	Да	String	Код кампании (в качестве альтернативы укажите `application`, `messages_ids` или `message_codes`).
`messages_ids`	Да	Array	ID сообщений (в качестве альтернативы укажите `application`, `campaign` или `message_codes`).
`link_template`	Обязательно, если указан `application` или `campaign`.	String	Фильтрует взаимодействия со ссылками в email по ключевому слову. В ответе API будут возвращены только те ссылки, URL которых содержит указанный текст. Например, если ваше письмо содержит ссылки `https://example.com/news` и `https://example.com/shop`, установка `"link_template": "shop"` вернет взаимодействия только для `https://example.com/shop`.
`email_content_code`	Нет	String	Уникальный идентификатор контента email.
`params`	Нет	Object	Определяет дополнительные опции ответа. Включает `with_full_links`, который добавляет список полных ссылок со статистикой.

Пример запроса

curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractions' \
--header 'Authorization: Api API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
   "filters": {
      "date_range": {
         "date_from": "string",           // Обязательный формат: 2000-01-01
         "date_to": "string"              // Обязательный формат: 2000-01-01
      },
      "campaign": "string",               // Код кампании (вместо него можно указать application, messages_ids или message_codes)
      "application": "string",            // Код приложения (вместо него можно указать campaign, messages_ids или message_codes)
      "messages_ids": [],                 // ID сообщений (вместо них можно указать application, campaign или message_codes)
      "messages_codes": [],               // Коды сообщений (вместо них можно указать application, campaign или message_ids)
      "link_template": "string",          // Шаблон ссылки (обязательно, если указан application или campaign)
      "email_content_code": "string"      // Уникальный идентификатор контента email.
   },
   "params": {
      "with_full_links": true             // Укажите, следует ли показывать подробную статистику. Список полных ссылок со статистикой будет передан в массиве full_links.
   }
}'

Коды ответов и примеры

{
  "items": [{
    "template": "string",
    "link": "string",
    "title": "string",
    "clicks": 0,
    "full_links": [{
      "full_link": "string",
      "clicks": 0
    }]
  }]
}

{
  "error": "exceeded the maximum date interval. Max interval: 30 days"
}

{
  "error": "account not found"
}

linksInteractionsDevices

Показывает пользователей, которые кликнули на ссылки в email-сообщениях

POST https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractionsDevices

Заголовки

Имя	Обязательный	Описание
`Authorization`	Да	Токен доступа API из панели управления Pushwoosh.

Параметры тела запроса

Имя	Обязательный	Тип	Описание
`date_range`	Нет	Object	Определяет отчетный период. Содержит `date_from` и `date_to`.
`filters`	Да	Object	Фильтры email.
`application`	Да	String	Код приложения Pushwoosh (в качестве альтернативы укажите `campaign`, `messages_ids` или `message_codes`).
`messages_codes`	Да	Array	Коды сообщений (в качестве альтернативы укажите `application`, `campaign` или `messages_ids`).
`campaign`	Да	String	Код кампании (в качестве альтернативы укажите `application`, `messages_ids` или `message_codes`).
`messages_ids`	Да	Array	ID сообщений (в качестве альтернативы укажите `application`, `campaign` или `message_codes`).
`link_template`	Обязательно, если указан `application` или `campaign`.	String	Фильтрует взаимодействия со ссылками в email по ключевому слову. В ответе API будут возвращены только те ссылки, URL которых содержит указанный текст. Например, если ваше письмо содержит ссылки `https://example.com/news` и `https://example.com/shop`, установка `"link_template": "shop"` вернет взаимодействия только для `https://example.com/shop`.
`email_content_code`	Нет	String	Уникальный идентификатор контента email.
`page`	Нет	Integer	Номер страницы для пагинации.
`per_page`	Нет	Integer	Количество результатов на странице (≤ 1000).

Пример запроса

curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractionsDevices' \
--header 'Authorization: Api API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
   "filters": {
      "date_range": {
         "date_from": "string",         // Обязательный формат: 2000-01-01
         "date_to": "string"            // Обязательный формат: 2000-01-01
      },
      "campaign": "string",             // Код кампании (вместо него можно указать application, messages_ids или message_codes)
      "application": "string",          // Код приложения (вместо него можно указать campaign, messages_ids или message_codes)
      "messages_ids": [],               // ID сообщений (вместо них можно указать application, campaign или message_codes)
      "messages_codes": [],             // Коды сообщений (вместо них можно указать application, campaign или message_ids)
      "link_template": "string",        // Шаблон ссылки (обязательно, если указан application или campaign)
      "email_content_code": "string"    // Уникальный идентификатор контента email.
   },
   "per_page": 100,
   "page": 0
}'

Коды ответов и примеры

{
  "total": 0,
  "items": [{
    "timestamp": "string",
    "link": "string",
    "hwid": "string"
  }]
}

{
  "error": "exceeded the maximum date interval. Max interval: 30 days"
}

{
  "error": "account not found"
}

bouncedEmails

POST https://api.pushwoosh.com/api/v2/statistics/emails/bouncedEmails

Предоставляет данные о жалобах на email, soft- и hard-bounce, включая дату, email-адрес и причину каждого возврата.

Авторизация

Авторизация осуществляется через токен доступа API в заголовке запроса.

Параметры тела запроса

Имя параметра	Тип	Описание	Обязательный
`application`	string	Код приложения Pushwoosh	Да
`message_code`	string	Код сообщения.	Обязательно, если не указаны `date range` или `campaign`
`campaign`	string	Код кампании.	Обязательно, если не указаны `message_code` или `date range`
`date_from`	string	Начальная дата для данных в формате `YYYY-MM-DDTHH:MM:SS.000Z` (стандарт ISO 8601).	Обязательно, если не указаны `message_code` или `campaign`
`date_to`	string	Конечная дата для данных в формате `YYYY-MM-DDTHH:MM:SS.000Z` (стандарт ISO 8601).	Обязательно, если не указаны `message_code` или `campaign`
`per_page`	int	Количество строк на странице, максимум 5000.	Да
`page`	int	Номер страницы, начиная с нуля.	Да
`type`	string	Тип возврата: Complaint, Softbounce, Hardbounce.	Нет

Пример запроса

{
  "application": "XXXXX-XXXXX",               // обязательно. Код приложения Pushwoosh
  "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // обязательно, если не указаны campaign или date range.
                                              //          Уникальный идентификатор сообщения
  "campaign": "XXXXX-XXXXX",                  // обязательно, если не указаны message_code или date range.
                                              //          Код кампании
  "date_from": "2024-07-20T00:00:00.000Z",    // обязательно, если не указаны message_code или campaign.
                                              //          Начальная дата в формате ISO 8601 "YYYY-MM-DDTHH:MM:SS.SSSZ"
  "date_to": "2024-07-20T00:00:00.000Z",      // обязательно, если не указаны message_code или campaign.
                                              //          Конечная дата в формате ISO 8601 "YYYY-MM-DDTHH:MM:SS.SSSZ"
  "per_page": 1000,                           // обязательно. Количество результатов на странице, максимум 5000
  "page": 5,                                  // опционально. Номер страницы, начиная с нуля
  "type": "Softbounce"                        // опционально. Тип возврата: Complaint, Softbounce, Hardbounce
}

Поля ответа

Имя поля	Тип	Описание
`total`	int	Общее количество строк.
`bounced_emails`	array	Массив деталей о возвращенных письмах.
├── `email`	string	Email-адрес, который был возвращен.
├── `date`	string	Дата возврата (формат: `YYYY-MM-DDTHH:MM:SS.000Z`).
├── `reason`	string	Причина возврата.
└── `type`	string	Тип возврата: Complaint, Softbounce, Hardbounce.

Пример ответа

{
  "total": 25,                             // Общее количество строк.
  "bounced_emails": [{
    "email": "example@example.com",        // Email-адрес, который был возвращен
    "date": "2024-07-20T00:00:00.000Z",    // Дата возврата в формате ISO 8601
    "reason": "Invalid recipient address", // Причина возврата
    "type": "Hardbounce"                   // Тип возврата: Complaint, Softbounce, Hardbounce
  }]
}