Message statistics

messages:list

Displays the list of sent messages.

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

Headers

Name	Required	Type	Description
`Authorization`	Yes	String	API access token from Pushwoosh Control Panel.

Request 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.
`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 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.
`per_page`	No	Integer	Number of results per page (≤ 1000).
`page`	No	Integer	Page number for pagination.

Example request

{
    "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

{
  "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 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
      },
      "metrics": [{
        "sends": 0,
        "opens": 0,
        "deliveries": 0,
        "hard_bounces": 0,
        "soft_bounces": 0,
        "rejects": 0,
        "confirmed_sends": 0,
        "unsubs": 0,
        "complaints": 0,
        "errors": 0
      }]
    }
  }]
}

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

{
  "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 parameters

Parameter Name	Type	Description	Required
`message_code`	string	Message code obtained from `/createMessage` API responses.	Yes
`platforms`	[int]	Platforms	No

Request example

{
  "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

{
  "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	Type	Description
`Authorization`	Required	String	API access token from Pushwoosh Control Panel.

Request body parameters

Name	Required/Optional	Type	Description
`message_id`	Optional	Integer	Select messages events by Message ID obtained from message history. Example: `12345678900`.
`message_code`	Optional	String	Select messages events by Message Code obtained from `/createMessage` API responses. Example: `"A444-AAABBBCC-00112233"`.
`campaign_code`	Optional	String	Select messages events by Campaign Code specified in your message payload. Example: `"AAAAA-XXXXX"`.
`hwid`	Optional	String or Array	Select messages events by HWID (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`	Optional	Integer	Maximum number of message events returned in a single response. Maximum value: `100000`.
`pagination_token`	Optional	String	Pagination token obtained from a previous `/getMessageLog` response. Use it to retrieve additional results.
`user_id`	Optional	String	Select messages events by a custom User ID. See `/registerUser` for more details.
`application_code`	Required	String	Select messages events by Pushwoosh application code.
`actions`	Optional	Array	Filter results by specific message actions. Possible values: `"sent"`, `"delivered"`, `"opened"`, `"inbox_delivered"`, `"inbox_read"`, `"inbox_opened"`, `"inbox_deleted"`.
`platforms`	Optional	Array	Array of target platforms to filter results. Possible values: `"ios"`, `"android"`, `"osx"`, `"windows"`, `"amazon"`, `"safari"`, `"chrome"`, `"firefox"`, `"ie"`, `"email"`, `"huawei_android"`.

Example request

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

{
  "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 statistics

linksInteractions

Displays statistics on link clicks in emails

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

Headers

Name	Required	Type	Description
`Authorization`	Yes	String	API access token from Pushwoosh Control Panel.

Request 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 (alternatively, specify `campaign`, `messages_ids`, or `message_codes`).
`messages_codes`	Yes	Array	Message codes (alternatively, specify `application`, `campaign`, or `messages_ids`).
`campaign`	Yes	String	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`	Yes	String	Required if `application` or `campaign` is specified. Defines the link template for tracking.
`email_content_code`	No	String	Unique identifier for the email content.
`params`	No	Object	Defines additional response options. Includes `with_full_links`, which adds a list of full links with statistics.

Request example

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

{
  "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

Shows users who clicked on links in emails

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

Headers

Name	Required	Type	Description
`Authorization`	Yes	String	API access token from the Pushwoosh Control Panel.

Request 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 (alternatively, specify `campaign`, `messages_ids`, or `message_codes`).
`messages_codes`	Yes	Array	Message codes (alternatively, specify `application`, `campaign`, or `messages_ids`).
`campaign`	Yes	String	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`	Yes	String	Required if `application` or `campaign` is specified. Defines the link template for tracking.
`email_content_code`	No	String	Unique identifier for the email content.
`page`	No	Integer	Page number for pagination.
`per_page`	No	Integer	Number of results per page (≤ 1000).

Request example

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

{
  "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

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 parameters

Parameter Name	Type	Description	Required
`application`	string	The application code.	Yes
`message_code`	string	The message code.	Required if `date range` or `campaign` is not provided
`campaign`	string	The 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

{
  "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

{
  "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
  }]
}