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. Must be provided in the following format: `Authorization: Api <Server Key>`.

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, filtered on message creation date. `date_from` and `date_to` must follow the `YYYY-MM-DD` format (e.g., `"2000-01-01"`); both days are included in full, so `date_from` and `date_to` set to the same date return that whole day. Dates are interpreted in UTC, not in your account timezone.
`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, `1` to `499`. Omit the parameter to get the default page size of 500 results; passing `500` or more explicitly is rejected with `400`.
`page`	No	Integer	Zero-based page number for pagination. See the deep pagination limit below.

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,                     // <= 499
    "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 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
      }]
    }
  }]
}

date_range spans more than 30 days:

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

page × per_page exceeds the deep pagination limit:

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

{
  "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 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 messages accepted for devices with notifications turned off in the OS settings. No banner is shown, but the message still reaches the app, and it appears in Message Inbox if the send has Save message to Inbox enabled. Counted as successful sends, not as errors.
`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",             // Sent to devices with notifications turned off, no banner 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)
    }]
  }
}

Delivery funnel

Use the delivery funnel to see at which stage a message or campaign lost its audience (errors, no delivery, no open) and why. Unlike totalsByIntervals, which returns hourly totals, the funnel breaks the audience down by stage and drop-out reason, one entry per channel, with a per-platform breakdown. The stage sequence differs by channel: see stage under GetDeliveryFunnelResponse fields below for which stages each channel carries. Both methods require a Server API token.

Both methods return the same response shape, GetDeliveryFunnelResponse, described once below.

getDeliveryFunnel

Returns one message’s funnel.

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

Headers

Name	Required	Description
`Authorization`	Yes	Server API token. Must be provided in the following format: `Authorization: Api <Server Key>`.

Request body parameters

Name	Required	Type	Description
`message_code`	Yes	String	Message code obtained from `/createMessage` API responses.
`platforms`	No	Array of integers	Platform codes to filter the funnel by. Omit to return every platform the message was sent to.

Example request

{
  "message_code": "A444-AAABBBCC-00112233",  // Message code from /createMessage
  "platforms": [1, 14]                        // Optional. iOS, Email
}

GetDeliveryFunnelResponse fields

Name	Type	Description
`channels`	Array	One entry per channel the message was sent on.
`window_from`, `window_to`	String or null	The period the funnel covers, based on the available data. `null` when `funnel_state` is not `FUNNEL_STATE_READY`.
`funnel_state`	String	`FUNNEL_STATE_READY`: the funnel below is populated. `FUNNEL_STATE_NO_EVENTS`: nothing has happened for this message yet. `FUNNEL_STATE_EXPIRED`: the message was sent too long ago. Funnel data for it is no longer available. `channels` is empty in both non-`READY` cases. An unknown, foreign, or deleted `message_code` is not one of these states, see the `404` response below.

channels[]

Name	Type	Description
`channel`	String	`CHANNEL_MOBILE_PUSH` (iOS, macOS, Android, Amazon, Huawei), `CHANNEL_WEB_PUSH` (Safari, Chrome, Firefox), `CHANNEL_EMAIL`, `CHANNEL_OTHER` (SMS, messengers, Wallet, Windows, Baidu, Xiaomi), `CHANNEL_APP_INBOX`.
`funnel`	Array	Funnel stages for this channel, see `funnel[]` below.
`deliveries_form`	String	Which breakdown the `STAGE_DELIVERIES` stage carries: `DELIVERIES_FORM_PER_DEVICE` (four disjoint rows, split by whether the device would show an alert and whether it confirmed) or `DELIVERIES_FORM_BASIC` (two rows, no alert-state split).
`basic_form_reason`	String	Meaningful only when `deliveries_form` is `DELIVERIES_FORM_BASIC`: `BASIC_FORM_REASON_RETENTION` (the message is too old for a per-device breakdown), `BASIC_FORM_REASON_UNAVAILABLE` (a per-device breakdown isn’t available for this account or message, for example a system message), `BASIC_FORM_REASON_NO_DELIVERIES` (nothing accepted yet), `BASIC_FORM_REASON_NOT_APPLICABLE` (the channel has no alert state at all, for example email or App Inbox). Otherwise `BASIC_FORM_REASON_UNSPECIFIED`: ignore this field unless `deliveries_form` is `DELIVERIES_FORM_BASIC`.
`confirmed_deliveries`	Object	`count` and a per-`platforms` breakdown of confirmed deliveries. Not capped at the `STAGE_DELIVERIES` count, so it can differ from it.

funnel[] (one stage)

Name	Type	Description
`stage`	String	`STAGE_AUDIENCE` (everyone the message targeted), `STAGE_SENT` (accepted by the push service or email provider), `STAGE_ERRORS` (rejected before it was accepted), `STAGE_DELIVERIES` (accepted, split by confirmation), `STAGE_OPENED` (unique devices that opened, or for App Inbox the entries the user tapped open), `STAGE_INTERACTIONS` (email only: clicked, unsubscribed, complained), `STAGE_REACHED`/`STAGE_READ` (App Inbox only, replace `STAGE_DELIVERIES`).
`count`	String	Total for the stage, as a numeric string.
`pieces`	Array	The stage’s own breakdown. Empty on `STAGE_ERRORS`, which uses `errors` instead. Each piece has `kind` (`KIND_PASSED` moved on to the next stage, `KIND_REASON` did not, `KIND_SUBSET` overlaps the other two and is never summed), `category` (see the value list below each stage), `count`, and a `platforms` breakdown.
`errors`	Array	`STAGE_ERRORS` only: `category` (see the value list below), `count`, `platforms`, and `codes`: the raw provider error codes grouped into this category (`platform`, `code`, `name`, `count`).
`platforms`	Array	The stage’s total, split by platform.

category values

STAGE_AUDIENCE:

ELIGIBLE_AUDIENCE (passed): not excluded by any of the reasons below.
FREQUENCY_CAPPING: skipped by frequency capping.
CONTROL_GROUP: held out as a control group.
UNSUBSCRIBED: the recipient had unsubscribed.
BOUNCED: the recipient’s address had previously bounced.
COMPLAINT: the recipient had previously marked a message as spam.
FILTERED_BY_CATEGORY: the recipient had opted out of this message’s category.

STAGE_ERRORS:

NO_TOKEN: the device had no push token or address to send to.
NO_DEVICE: no matching device was found.
PLATFORM_DISABLED: the platform is disabled for this app.
INVALID_TOKEN: the provider rejected the device token or address as invalid.
QUOTA_EXCEEDED: the provider rate-limited the send.
INVALID_CONTENT: the message couldn’t be sent as composed. Most often the template itself failed to build, for example a broken Connected Content or Liquid block, rather than the provider rejecting it.
INVALID_CONFIGURATION: the account’s own provider setup is broken, for example wrong credentials, a deleted Firebase project, or a disallowed APNs topic.
PROVIDER_ERROR: the provider returned an error outside the categories above.
INTERNAL_ERROR: Pushwoosh failed to process the send.
UNCLASSIFIED_ERROR: a drop-out that matches none of the categories above. Expected to be rare.

STAGE_DELIVERIES, DELIVERIES_FORM_PER_DEVICE:

DISPLAYABLE_CONFIRMED (passed): the device showed an alert and confirmed receipt.
DISPLAYABLE_NO_CONFIRMATION: the device would show an alert but hasn’t confirmed receipt yet.
NOT_DISPLAYABLE_CONFIRMED (passed): a silent push confirmed receipt.
NOT_DISPLAYABLE_NO_CONFIRMATION: a silent push hasn’t confirmed receipt yet.

STAGE_DELIVERIES, DELIVERIES_FORM_BASIC:

CONFIRMED_BY_DEVICE (passed): the device confirmed receipt.
NO_CONFIRMATION: not confirmed yet.

Email also adds, as a subset overlapping CONFIRMED_BY_DEVICE:

BOUNCED_HARD (subset): the address is permanently undeliverable.
BOUNCED_SOFT (subset): the address is temporarily undeliverable, for example a full mailbox.

BOUNCED_HARD may also split into these subset rows:

BOUNCED_HARD_GENERAL: permanently undeliverable, no more specific reason available.
BOUNCED_HARD_MAILBOX_FULL: the recipient’s mailbox is full.
BOUNCED_HARD_MAILBOX_INACTIVE: the recipient’s mailbox no longer exists.
BOUNCED_HARD_SUPPRESSED: the provider has the address blocklisted.
BOUNCED_HARD_UNDETERMINED: permanently undeliverable, reason not determined.

BOUNCED_SOFT may also split into these subset rows:

BOUNCED_SOFT_GENERAL: temporarily undeliverable, no more specific reason available.
BOUNCED_SOFT_MAILBOX_FULL: the recipient’s mailbox was full at the time.
BOUNCED_SOFT_CONTENT_REJECTED: the recipient’s mail server rejected the message content.
BOUNCED_SOFT_SPAM: the recipient’s mail server flagged the message as spam.
BOUNCED_SOFT_MESSAGE_TOO_LARGE: the message was too large for the recipient’s mailbox.
BOUNCED_SOFT_ATTACHMENT_REJECTED: the recipient’s mail server rejected an attachment.
BOUNCED_SOFT_CUSTOM_TIMEOUT_EXCEEDED: the recipient’s mail server took too long to respond.
BOUNCED_SOFT_UNDETERMINED: temporarily undeliverable, reason not determined.
BOUNCED_UNDETERMINED: the recipient’s server accepted the email but never confirmed delivery; the outcome is unknown and the address isn’t suppressed. Counts as soft.

BOUNCED_UNCLASSIFIED is a bounce, hard or soft, that doesn’t match any subtype above. Expected to be rare, and not a value to build logic on.

STAGE_OPENED, email only (other channels report the stage’s count with no pieces):

OPENED_BY_RECIPIENT (passed): opened by a person.
MACHINE_OPENS_ONLY: opened only by an automated scanner.
OPEN_TYPE_UNKNOWN: couldn’t be classified as a person or a scanner.
MACHINE_OPENS_AMPP (subset): replaces the three rows above when the person/scanner split isn’t available for this message. Counts Apple Mail Privacy Protection’s own machine-open number instead, and overlaps the stage total.

STAGE_INTERACTIONS, email only:

CLICKED_ONLY (passed): clicked a link, stayed subscribed.
CLICKED_AND_UNSUBSCRIBED: clicked a link and unsubscribed.
CLICKED_AND_COMPLAINED: clicked a link and marked the message as spam.
UNSUBSCRIBED_WITHOUT_CLICK: unsubscribed without clicking.
COMPLAINED_WITHOUT_CLICK: marked the message as spam without clicking.

STAGE_REACHED, App Inbox only:

REACHED (passed): the entry was fetched by the app at least once.
NOT_FETCHED_YET: not fetched yet.

STAGE_READ, App Inbox only:

READ (passed): marked as read.
DISMISSED_UNREAD: deleted by the user without being read.
UNREAD: still sitting unread in the inbox.
EXPIRED_UNREAD: same as UNREAD, but the entry has since expired out of the inbox.
DISMISSED (subset): every deleted entry, read or not. Overlaps READ and DISMISSED_UNREAD.

Response codes

{
  "channels": [{
    "channel": "CHANNEL_MOBILE_PUSH",
    "funnel": [
      { "stage": "STAGE_AUDIENCE", "count": "10000", "pieces": [
        { "kind": "KIND_PASSED", "category": "ELIGIBLE_AUDIENCE", "count": "10000", "platforms": [{ "platform": 1, "count": "10000" }] }
      ], "errors": [], "platforms": [{ "platform": 1, "count": "10000" }] },
      { "stage": "STAGE_SENT", "count": "9820", "pieces": [], "errors": [], "platforms": [{ "platform": 1, "count": "9820" }] },
      { "stage": "STAGE_ERRORS", "count": "180", "pieces": [], "errors": [
        { "category": "INVALID_TOKEN", "count": "180", "platforms": [{ "platform": 1, "count": "180" }], "codes": [
          { "platform": 1, "code": 1002, "name": "BadDeviceToken", "count": "180" }
        ] }
      ], "platforms": [{ "platform": 1, "count": "180" }] },
      { "stage": "STAGE_DELIVERIES", "count": "9820", "pieces": [
        { "kind": "KIND_PASSED", "category": "DISPLAYABLE_CONFIRMED", "count": "8000", "platforms": [{ "platform": 1, "count": "8000" }] },
        { "kind": "KIND_REASON", "category": "DISPLAYABLE_NO_CONFIRMATION", "count": "820", "platforms": [{ "platform": 1, "count": "820" }] },
        { "kind": "KIND_PASSED", "category": "NOT_DISPLAYABLE_CONFIRMED", "count": "900", "platforms": [{ "platform": 1, "count": "900" }] },
        { "kind": "KIND_REASON", "category": "NOT_DISPLAYABLE_NO_CONFIRMATION", "count": "100", "platforms": [{ "platform": 1, "count": "100" }] }
      ], "errors": [], "platforms": [{ "platform": 1, "count": "9820" }] },
      { "stage": "STAGE_OPENED", "count": "3120", "pieces": [], "errors": [], "platforms": [{ "platform": 1, "count": "3120" }] }
    ],
    "deliveries_form": "DELIVERIES_FORM_PER_DEVICE",
    "basic_form_reason": "BASIC_FORM_REASON_UNSPECIFIED",
    "confirmed_deliveries": { "count": "8900", "platforms": [{ "platform": 1, "count": "8900" }] }
  }],
  "window_from": "2026-09-01T00:00:00Z",
  "window_to": "2026-09-01T00:05:00Z",
  "funnel_state": "FUNNEL_STATE_READY"
}

An empty channels array with funnel_state: "FUNNEL_STATE_NO_EVENTS" means nothing has happened for this message yet. This is not an error. A message_code sent too long ago for funnel data to be available also still returns 200, with an empty channels array and funnel_state: "FUNNEL_STATE_EXPIRED".

An unknown message_code, one that belongs to a different account, or one that has since been deleted:

{
  "error": "message not found"
}

{
  "error": "invalid auth token"
}

getCampaignDeliveryFunnel

Sums getDeliveryFunnel over a campaign’s messages. Unique counts are calculated per message: a subscriber reached by several messages in the campaign is counted once for each message.

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

Headers

Name	Required	Description
`Authorization`	Yes	Server API token. Must be provided in the following format: `Authorization: Api <Server Key>`.

Request body parameters

Name	Required	Type	Description
`campaign_code`	Yes	String	Campaign code.
`platforms`	No	Array of integers	Platform codes to filter the funnel by. Omit to return every platform the campaign was sent to.

Example request

{
  "campaign_code": "AAAAA-XXXXX",  // Campaign code
  "platforms": [1, 14]             // Optional. iOS, Email
}

Response

Same shape as GetDeliveryFunnelResponse above.

Response codes

An empty audience for the given campaign_code and platforms still returns 200 with an empty channels array and funnel_state: "FUNNEL_STATE_NO_EVENTS". A campaign sent too long ago for funnel data to be available also still returns 200, with an empty channels array and funnel_state: "FUNNEL_STATE_EXPIRED". Neither is an error.

An unknown campaign_code, one that belongs to a different account, or one whose messages have all been deleted. A campaign with only some messages deleted is unaffected: the deleted ones still count toward its funnel.

{
  "error": "campaign not found"
}

{
  "error": "invalid auth token"
}

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 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 obtained from `/createMessage` API responses. Example: `"A444-AAABBBCC-00112233"`.
`campaign_code`	No	String	Select messages events by Campaign code specified in your message payload. Example: `"AAAAA-XXXXX"`.
`hwid`	No	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`	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. See `/registerUser` for more details.
`application_code`	Yes	String	Select messages events by Pushwoosh application code
`actions`	No	Array	Filter results by specific message actions. Possible values: `"sent"`, `"delivered"`, `"opened"`, `"reject"`, `"create"`, `"inbox_delivered"`, `"inbox_read"`, `"inbox_opened"`, `"inbox_deleted"`. `"create"` events are excluded from the response by default. Include `"create"` in this array to see them. `"delivered"` events additionally require delivery statistics to be enabled on the account.
`platforms`	No	Array	Array of target platforms to filter results. Possible values: `"unknown"`, `"ios"`, `"blackberry"`, `"android"`, `"windows phone"`, `"osx"`, `"windows"`, `"amazon"`, `"safari"`, `"chrome"`, `"firefox"`, `"ie"`, `"email"`, `"fb messenger"`, `"baidu android"`, `"huawei android"`, `"sms"`, `"xiaomi"`, `"web"`, `"whatsapp"`, `"line"`, `"kakao"`, `"telegram"`, `"apple wallet"`, `"google wallet"`, `"viber"`.
`message_type`	No	String	Filter results by message flow. `"all"` (default if omitted) returns everything, `"broadcast"` returns only mass messages (`message_id != 0`), `"transactional"` returns only messages with `message_id = 0`, including those sent from Customer Journey.

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", "delivered", "opened", "reject", "create", "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, lowercase only. Possible values: "unknown", "ios", "blackberry", "android", "windows phone", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "fb messenger", "baidu android", "huawei android", "sms", "xiaomi", "web", "whatsapp", "line", "kakao", "telegram", "apple wallet", "google wallet", "viber"
   "message_type": "broadcast"                     // optional, "all" (default), "broadcast" (message_id != 0), or "transactional" (message_id = 0, includes Customer Journey sends)
}'

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"
  }, {
    "timestamp": "2000-01-25T11:19:30Z",
    "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": "reject",
    "status": "failed",
    "error_reason": "invalid device token",
    "payload": "SOME_PAYLOAD_STRING"
  }]
}

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

{
  "error": "account not found"
}

Each entry in data also carries error_reason (string, populated with the failure reason when status is "failed") and an optional payload (string).

A response page can come back shorter than the requested limit. That alone doesn’t mean the export is finished.

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 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 (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`	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.
`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	Description
`Authorization`	Yes	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 (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`	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.
`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 body parameters

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