# Message statistics ## messages:list Displays the list of sent messages. `POST` `https://api.pushwoosh.com/api/v2/messages:list` ##### Headers | Name
| Required
| Description
| |----------------|----------|------------------------------------------------------------------------------------------------------| | `Authorization`| Yes | [Server API token](/developer/api-reference/api-access-token/#server-api-token). Must be provided in the following format: `Authorization: Api `. | ##### Request body parameters | Name
| Required
| Type
| Description
| |--------------------------------------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------| | `platforms` | No | Array | Message platforms. Possible values: `"IOS"`, `"ANDROID"`, `"OSX"`, `"WINDOWS"`, `"AMAZON"`, `"SAFARI"`, `"CHROME"`, `"FIREFOX"`, `"IE"`, `"EMAIL"`, `"HUAWEI_ANDROID"`, `"SMS"`. | | `date_range` | No | Object | Reporting period. `date_from` and `date_to` must follow the `YYYY-MM-DD` format (e.g., `"2000-01-01"`). | | `campaign` | No | String | [Campaign code](/developer/api-reference/api-identifiers/#campaign-code) | | `filters` | Yes | Object | Message filters. | | `source` | No | String | Message source. For example: `AB_TEST`, `API`, `AUTO_PUSH`, `CP`, `CSV`, `CUSTOMER_JOURNEY`, `EMAIL_API`, `EMAIL_CP`, `GEO_ZONE`, `PUSH_ON_EVENT`, `RSS`. | | `messages_codes` | No | Array | [Message codes](/developer/api-reference/api-identifiers/#message-code) obtained from `/createMessage` API responses. | | `messages_ids` | No | Array | Message IDs obtained from the Message History | | `params` | No | Object | Specify whether to show message details and metrics. Set `with_details: true` to include the `"details"` object and `with_metrics: true` to include the `"metrics"` object in the response. | | `application` | Yes | String | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code). | | `per_page` | No | Integer | Number of results per page (≤ 1000). | | `page` | No | Integer | Page number for pagination. | ##### Example request ```json { "filters": { "platforms": [], // IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS "date_range": { "date_from": "string", // Required format: 2000-01-01 "date_to": "string" // Required format: 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", // Campaign code "messages_ids": [], // Message IDs "messages_codes": [], // Message codes "application": "string" // Pushwoosh application code }, "params": { "with_details": true, // Add message details to the response ("details" object) "with_metrics": true // Add message metrics to the response ("metrics" object) }, "per_page": 20, // <= 1000 "page": 0 } ```
Response codes and examples ```json { "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": [ // tag conditions (see /developer/api-reference/messages-api/#tag-conditions) TAG_CONDITION1, TAG_CONDITION2, ..., TAG_CONDITIONN ], "conditions_operator": "AND", // logical operator for conditions arrays; possible values: 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": [ // tag conditions (see Messages-api - tag-conditions) TAG_CONDITION1, TAG_CONDITION2, ..., TAG_CONDITIONN ], "conditions_operator": "AND" // logical operator for conditions arrays; possible values: 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 }] } }] } ``` ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` ```json { "error": "account not found" } ```
## totalsByIntervals Returns metrics and conversion data based on the message code, aggregated by hour. **POST** `https://api.pushwoosh.com/api/v2/statistics/messages/totalsByIntervals` ##### Authorization Authorization is handled via the API Access Token in the request header. ##### Request body parameters | Parameter Name
| Type
| Description | Required | |----------------|--------|-----------------------------|----------| | `message_code` | string | [Message code](/developer/api-reference/api-identifiers/#message-code) obtained from `/createMessage` API responses. | Yes | | `platforms` | [int] | [Platforms](/developer/api-reference/messages-api/api-prerequisites/#platforms) | No | ##### Request example ```json { "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // required. Unique message identifier "platforms": [1, 3, 7, 10, 11, 12] // optional. List of platform codes } ``` ##### Response fields | Name | Type | Description | |-------------------|--------|-------------------------------------------------------------------| | **`metrics`** | **array** | **Contains an array of message metrics** | | `timestamp` | string | The time of the metric. | | `platform` | int | The platform code (e.g., iOS, Android). | | `sends` | string | The number of sent messages. | | `opens` | string | The number of opened messages. | | `deliveries` | string | The number of delivered messages. | | `inbox_opens` | string | The number of inbox opens. | | `unshowable_sends`| string | The number of sent messages that could not be shown. | | `errors` | string | The number of errors. | | **`conversion`** | **object** | **Contains conversion data** | | `sends` | string | The total number of sent messages. | | `opens` | string | The total number of opened messages. | | **`events`** | **array** | **An array of events with their statistics** | | `name` | string | The name of the event (e.g., cart add). | | `hits` | string | The number of hits. | | `conversion` | float | The conversion rate relative to opens. | | `revenue` | float | The revenue (only for events with `__amount` and `__currency` attributes). | ##### Response example ```json { "metrics": [{ "timestamp": "2024-08-03 15:00:00", // Timestamp of the metrics in "YYYY-MM-DD HH:MM:SS" format "platform": 3, // Platform code "sends": "55902", // Number of messages sent "opens": "382", // Number of messages opened "deliveries": "22931", // Number of messages delivered "inbox_opens": "0", // Number of messages opened in the inbox "unshowable_sends": "2", // Number of messages that couldn't be shown "errors": "0" // Number of errors encountered }], "conversion": { "sends": "55902", // Total number of messages sent "opens": "772", // Total number of messages opened "events": [{ "name": "cart_add", // Name of the event "hits": "96", // Number of hits for the event "conversion": 0.12, // Conversion rate relative to opens "revenue": 0 // Revenue generated by the event (only for events with amount/currency attributes) }] } } ``` ## getMessageLog Displays detailed information about the messages sent. `POST` `https://api.pushwoosh.com/api/v2/statistics/getMessageLog` ##### Headers | Name
| Required
| Description
| |-----------------|----------|----------------------------------------------------------------------------------------------------------------------------| | `Authorization` | Required | [API access token](/developer/api-reference/api-access-token/) from Pushwoosh Control Panel. | ##### Request body parameters | Name
| Required
| Type
| Description
| |--------------------|------------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `message_id` | No | Integer | Select messages events by Message ID obtained from message history. Example: `12345678900`. | | `message_code` | No | String | Select messages events by [Message code](/developer/api-reference/api-identifiers/#message-code) obtained from `/createMessage` API responses. Example: `"A444-AAABBBCC-00112233"`. | | `campaign_code` | No | String | Select messages events by [Campaign code](/developer/api-reference/api-identifiers/#campaign-code) specified in your message payload. Example: `"AAAAA-XXXXX"`. | | `hwid` | No | String or Array | Select messages events by [HWID (Hardware ID)](/developer/api-reference/api-identifiers/#hardware-id ) or an array of HWIDs. | | `date_from` | Required if `message_id`, `message_code`, or `campaign_code` is not provided | Datetime | Start date for filtering messages. Format: `"YYYY-MM-DD HH:MM:SS"`. Example: `"2000-01-25 00:00:00"`. | | `date_to` | Required if `message_id`, `message_code`, or `campaign_code` is not provided | Datetime | End date for filtering messages. Format: `"YYYY-MM-DD HH:MM:SS"`. Example: `"2000-01-26 00:00:00"`. | | `limit` | No | Integer | Maximum number of message events returned in a single response. Maximum value: `100000`. | | `pagination_token` | No | String | Pagination token obtained from a previous `/getMessageLog` response. Use it to retrieve additional results. | | `user_id` | No | String | Select messages events by a custom [User ID](/developer/api-reference/api-identifiers/#user-id). See `/registerUser` for more details. | | `application_code` | Yes | String | Select messages events by [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) | | `actions` | No | Array | Filter results by specific message actions. Possible values: `"sent"`, `"delivered"`, `"opened"`, `"inbox_delivered"`, `"inbox_read"`, `"inbox_opened"`, `"inbox_deleted"`. | | `platforms` | No | Array | Array of target platforms to filter results. Possible values: `"ios"`, `"android"`, `"osx"`, `"windows"`, `"amazon"`, `"safari"`, `"chrome"`, `"firefox"`, `"ie"`, `"email"`, `"huawei_android"`. | ##### Example request ```shell 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", // optional, token for pagination "limit": 1000, // optional, the max number of entries for a single response "application_code": "XXXXX-XXXXX", // Pushwoosh app code "message_code": "A444-AAABBBCC-00112233", // optional, message code obtained from /createMessaage request "message_id": 1234567890, // optional, message ID obtained from Pushwoosh Control Panel "campaign_code": "AAAAA-XXXXX", // optional, code of a campaign to get the log for "hwid": "aaazzzqqqqxxx", // optional, hardware ID of a specific device targeted with a message "user_id": "user_123", // optional, ID of a user targeted with the message "date_from": "2000-01-25 00:00:00", // optional, start of the stats period "date_to": "2000-02-10 23:59:59", // optional, end of the stats period "actions": ["opened", "inbox_opened"], // optional, used for results filtration. Possible values: "sent", "opened", "delivered", "inbox_delivered", "inbox_read", "inbox_opened", "inbox_deleted". The response will include all the messages with the specified action(s). "platforms": ["ios", "chrome"] // optional, used for results filtration. Possible values: "ios", "android", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "huawei android" }' ```
Response codes and examples ```json { "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" }] } ``` ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` ```json { "error": "account not found" } ```
## Email statistics ### linksInteractions Displays statistics on link clicks in emails `POST` `https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractions` ##### Headers | Name
| Required
| Description | |-----------------|----------|-------------------------------------------------------------------------------------------------------| | `Authorization` | Yes | [API access token](/developer/api-reference/api-access-token/) from Pushwoosh Control Panel. | ##### Request body parameters | Name
| Required
| Type | Description | |--------------------|----------|--------|------------------------------------------------------------------------------------------------------| | `date_range` | No | Object | Defines the reporting period. Contains `date_from` and `date_to`. | | `filters` | Yes | Object | Email filters. | | `application` | Yes | String | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) (alternatively, specify `campaign`, `messages_ids`, or `message_codes`). | | `messages_codes` | Yes | Array | [Message codes](/developer/api-reference/api-identifiers/#message-code) (alternatively, specify `application`, `campaign`, or `messages_ids`). | | `campaign` | Yes | String | [Campaign code](/developer/api-reference/api-identifiers/#campaign-code) (alternatively, specify `application`, `messages_ids`, or `message_codes`). | | `messages_ids` | Yes | Array | Message IDs (alternatively, specify `application`, `campaign`, or `message_codes`). | | `link_template` | Required if `application` or `campaign` is specified. | String | Filters email link interactions by keyword. Only links that include the specified text in their URL will be returned in the API response. For example, if your email contains links like `https://example.com/news` and `https://example.com/shop`, setting "link_template": "shop" will return interactions for `https://example.com/shop` only. | | `email_content_code` | No | String | [Unique identifier for the email content](/developer/api-reference/api-identifiers/#email-content-code). | | `params` | No | Object | Defines additional response options. Includes `with_full_links`, which adds a list of full links with statistics. | ##### Request example ```shell 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", // Required format: 2000-01-01 "date_to": "string" // Required format: 2000-01-01 }, "campaign": "string", // Campaign code (you can specify application, messages_ids, or message_codes instead) "application": "string", // Application code (you can specify campaign, messages_ids, or message_codes instead) "messages_ids": [], // Message IDs (you can specify application, campaign, or message_codes instead) "messages_codes": [], // Message codes (you can specify application, campaign, or message_ids instead) "link_template": "string", // Link template (required if application or campaign is specified) "email_content_code": "string" // Unique identifier for the email content. }, "params": { "with_full_links": true // Specify whether to show detailed statistics. A list of full links with statistics will be passed in the full_links array. } }' ``` ##### Response codes and examples ```json { "items": [{ "template": "string", "link": "string", "title": "string", "clicks": 0, "full_links": [{ "full_link": "string", "clicks": 0 }] }] } ``` ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` ```json { "error": "account not found" } ``` ### linksInteractionsDevices Shows users who clicked on links in emails `POST` `https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractionsDevices` ##### Headers | Name
| Required
| Description | |-----------------|----------|------------------------------------------------------------------------------------------------------| | `Authorization` | Yes | [API access token](/developer/api-reference/api-access-token/) from the Pushwoosh Control Panel. | ##### Request body parameters | Name
| Required
| Type | Description | |--------------------|----------|---------|------------------------------------------------------------------------------------------------------| | `date_range` | No | Object | Defines the reporting period. Contains `date_from` and `date_to`. | | `filters` | Yes | Object | Email filters. | | `application` | Yes | String | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) (alternatively, specify `campaign`, `messages_ids`, or `message_codes`). | | `messages_codes` | Yes | Array | [Message codes](/developer/api-reference/api-identifiers/#message-code) (alternatively, specify `application`, `campaign`, or `messages_ids`). | | `campaign` | Yes | String | [Campaign code](/developer/api-reference/api-identifiers/#campaign-code) (alternatively, specify `application`, `messages_ids`, or `message_codes`). | | `messages_ids` | Yes | Array | Message IDs (alternatively, specify `application`, `campaign`, or `message_codes`). | | `link_template` | Required if `application` or `campaign` is specified. | String | Filters email link interactions by keyword. Only links that include the specified text in their URL will be returned in the API response. For example, if your email contains links like `https://example.com/news` and `https://example.com/shop`, setting "link_template": "shop" will return interactions for `https://example.com/shop` only. | | `email_content_code` | No | String | [Unique identifier for the email content](/developer/api-reference/api-identifiers/#email-content-code). | | `page` | No | Integer | Page number for pagination. | | `per_page` | No | Integer | Number of results per page (≤ 1000). | ##### Request example ```shell 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", // Required format: 2000-01-01 "date_to": "string" // Required format: 2000-01-01 }, "campaign": "string", // Campaign code (you can specify application, messages_ids, or message_codes instead) "application": "string", // Application code (you can specify campaign, messages_ids, or message_codes instead) "messages_ids": [], // Message IDs (you can specify application, campaign, or message_codes instead) "messages_codes": [], // Message codes (you can specify application, campaign, or message_ids instead) "link_template": "string", // Link template (required if application or campaign is specified) "email_content_code": "string" // Unique identifier for the email content. }, "per_page": 100, "page": 0 }' ``` ##### Response codes and examples ```json { "total": 0, "items": [{ "timestamp": "string", "link": "string", "hwid": "string" }] } ``` ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` ```json { "error": "account not found" } ``` ### bouncedEmails **POST** `https://api.pushwoosh.com/api/v2/statistics/emails/bouncedEmails` Provides data on email complaints, soft bounces, and hard bounces, including the date, email address, and reason for each bounce. ##### Authorization Authorization is handled via the API Access Token in the request header. ##### Request body parameters | Parameter Name | Type | Description | Required | |----------------|--------|--------------------------------------------------------------------------------------------------|------------------------------------------------| | `application` | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) | Yes | | `message_code` | string | [Message code](/developer/api-reference/api-identifiers/#message-code). | Required if `date range` or `campaign` is not provided | | `campaign` | string | [Campaign code](/developer/api-reference/api-identifiers/#campaign-code). | Required if `message_code` or `date range` is not provided | | `date_from` | string | The start date for the data in the format `YYYY-MM-DDTHH:MM:SS.000Z` (ISO 8601 standard). | Required if `message_code` or `campaign` is not provided | | `date_to` | string | The end date for the data in the format `YYYY-MM-DDTHH:MM:SS.000Z` (ISO 8601 standard). | Required if `message_code` or `campaign` is not provided | | `per_page` | int | The number of rows per page, maximum 5000. | Yes | | `page` | int | The page number, starting from zero. | Yes | | `type` | string | The type of bounce: Complaint, Softbounce, Hardbounce. | No | ##### Request example ```json { "application": "XXXXX-XXXXX", // required. Pushwoosh app code "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // required if campaign or date range is not provided. // Unique message identifier "campaign": "XXXXX-XXXXX", // required if message_code or date range is not provided. // Campaign code "date_from": "2024-07-20T00:00:00.000Z", // required if message_code or campaign is not provided. // Start date in ISO 8601 format "YYYY-MM-DDTHH:MM:SS.SSSZ" "date_to": "2024-07-20T00:00:00.000Z", // required if message_code or campaign is not provided. // End date in ISO 8601 format "YYYY-MM-DDTHH:MM:SS.SSSZ" "per_page": 1000, // required. Number of results per page, maximum 5000 "page": 5, // optional. Page number, starting from zero "type": "Softbounce" // optional. The type of bounce: Complaint, Softbounce, Hardbounce } ``` ##### Response fields | Field Name | Type | Description | |-------------------|--------|-----------------------------------------------------------------------------| | `total` | int | The total count of rows. | | `bounced_emails` | array | An array of bounced email details. | | ├── `email` | string | The email address that bounced. | | ├── `date` | string | The date of the bounce (format: `YYYY-MM-DDTHH:MM:SS.000Z`). | | ├── `reason` | string | The reason for the bounce. | | └── `type` | string | The type of bounce: Complaint, Softbounce, Hardbounce. | ##### Response example ```json { "total": 25, // Total count of rows. "bounced_emails": [{ "email": "example@example.com", // Email address that bounced "date": "2024-07-20T00:00:00.000Z", // Bounce date in ISO 8601 format "reason": "Invalid recipient address", // Reason for the bounce "type": "Hardbounce" // Type of bounce: Complaint, Softbounce, Hardbounce }] } ```