Statistics API v2

messages:list

Displays the list of sent messages.

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

Headers

Name	Type	Description
Authorization*	String	API access token from Pushwoosh Control Panel

Request Body

Name	Type	Description
platforms	Array	Message platforms (see possible values in a request example below)
date_range	Object	Reporting period (see details in a request example below)
campaign	String	Campaign code
filters*	Object	Message filters
source	String	Message source (see possible values in a request example below)
messages_codes	Array	Message codes
messages_ids	Array	Message IDs
params	Object	Specify whether to show message details and metrics (see details in a request example below)
application*	String	Pushwoosh application code
per_page	Integer	Number of results per page ( <= 1000)
page	Integer	Page number for pagination

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

curl --location --request POST 'https://api.pushwoosh.com/api/v2/messages:list' \
--header 'Authorization: Api API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
   "filters": {
      "platforms": [], // IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS, XIAOMI
      "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" // 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
}'

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	The code of the message	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	Type	Description
Authorization*	String	API access token from Pushwoosh Control Panel.

Request Body

Name	Type	Description
message_id	Integer	Select messages events by Message IDs obtained from message history. For example, 12345678900.
message_code	String	Select messages events by message codes obtained from /createMessage API responses. For example, A444-AAABBBCC-00112233.
campaign_code	String	Select messages events by campaign codes specified in your messages payload. For example, AAAAA-XXXXX.
hwid	String or Array	Select messages events by an HWID or by array or HWID’s.
date_from	Datetime	Select messages events by the date and time they’ve launched (max 30 days from the current date). For example, 2000-01-25 00:00:00.
limit	Integer	Limits the number of messages events in single response. Max value is 100000.
date_to	Datetime	Select messages events by the date and time to stop sending. For example, 2000-01-26 00:00:00
pagination_token	String	pagination_token obtained from previous /getMessageLog response.
user_id	String	Select messages events by an custom user_id. For more info see /registerUser
application_code	String	Select messages events by application code
actions	array	Array of message actions to filter the results by. Possible values: “sent”, “delivered”, “opened”, “inbox_delivered”, “inbox_read”, “inbox_opened”, “inbox_deleted”. The response will include all the messages with the specified action(s).
platforms	array	Array of target platforms to filter the results by. Possible values: “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"
}

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"
}'

{
  "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",         // actions returned:         sent, opened, delivered;
                              // for pushes sent to inbox: inbox_delivered, inbox_read, inbox_opened, inbox_delete;
    "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",   // actions returned:         sent, opened, delivered;
                             // for pushes sent to inbox: inbox_delivered, inbox_read, inbox_opened, inbox_delete;
    "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": "inbox_delivered", // actions returned:         sent, opened, delivered;
                                 // for pushes sent to inbox: inbox_delivered, inbox_read,
                                 //                           inbox_opened, inbox_delete;
    "push_alerts_enabled": "true"
  }]
}

/emails/linksInteractions

Displays statistics on link clicks in emails

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

Headers

Name	Type	Description
Authorization*	String	API access token from Pushwoosh Control Panel

Request Body

Name	Type	Description
date_range	Object	Reporting period (see details in a request example below)
filters*	Object	Email filters
application*	String	Pushwoosh application code (you can specify `campaign`, `messages_ids`, or `message_codes` instead)
messages_codes*	Array	Message codes (you can specify `application`, `campaign`, or `message_ids` instead)
campaign*	String	Campaign code (you can specify `application`, `messages_ids`, or `message_codes` instead)
messages_ids*	Array	Message IDs (you can specify `application`, `campaign`, or `message_codes` instead)
link_template*	String	Link template (required if `application` or `campaign` is specified)
template	String	Email template code
params	Object	Specify whether to show detalied statistic (a list of full links with statistics will be passed in the `full_links` array)

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

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)
      "template": "string" // Email template code
   },
   "params": {
      "with_full_links": true // Specify whether to show detalied statistics. A list of full links with statistics will be passed in the full_links array.
   }
}'

/emails/linksInteractionsDevices

Shows users who clicked on links in emails

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

Headers

Name	Type	Description
Authorization*	String	API access token from Pushwoosh Control Panel

Request Body

Name	Type	Description
date_range	Object	Reporting period (see details in a request example below)
filters*	Object	Email filters
application*	String	Pushwoosh application code (you can specify `campaign`, `messages_ids`, or `message_codes` instead)
messages_codes*	Array	Message codes (you can specify `application`, `campaign`, or `message_ids` instead)
campaign*	String	Campaign code (you can specify `application`, `messages_ids`, or `message_codes` instead)
messages_ids*	Array	Message IDs (you can specify `application`, `campaign`, or `message_codes` instead)
link_template*	String	Link template (required if `application` or `campaign` is specified)
template	String	Email template code
page	Integer	Page number for pagination
per_page	Integer	Number of results per page (<= 1000)

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

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

{
  "error": "account not found"
}

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)
      "template": "string" // Email template code
   },
   "per_page": 100,
   "page": 0
}'

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