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

200: OK

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

400: Bad Request Error in the request

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

401: Unauthorized Incorrect API access token

{
  "error": "account not found"
}

500: Internal Server Error Internal error

Example request

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

Note

For iOS, please make sure that you have added the Notification Service Extension to your project for tracking push delivery. Learn more

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”.

200: OK

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

400: Bad Request

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

401: Unauthorized

{
  "error": "account not found"
}

500: Internal Server Error

Caution

One of the following fields is required:
- message_id
- message_code
- campaign_code
- hwid
- user_id
- date_from and date_to

Consider applying various filtration params to get the most of your messages stats.

Note

Data can be downloaded up to a maximum of 30 days from the current time.

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

Example response

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

Note

For iOS, please make sure that you have added the Notification Service Extension to your project for tracking push delivery. Learn more

/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)

200: OK

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

400: Bad Request

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

401: Unauthorized

{
  "error": "account not found"
}

500: Internal Server Error

Example request

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)

200: OK

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

400: Bad Request

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

401: Unauthorized

{
  "error": "account not found"
}

500: Internal Server Error

Example request

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