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

Deep pagination

messages:list rejects requests where page × per_page exceeds 100000 results. Narrow the date_range or use a smaller per_page to stay within the limit.

total is the exact number of messages matching the filters while that number is at or below 100000, and stops at 100001 above it — more than this endpoint can page through. Do not size a page loop past that limit: pages beyond it are rejected, not empty. To pull a period that holds more messages than that, narrow the date_range per request, or use the asynchronous export, which writes the whole period to one CSV file without paging.

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

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

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

401: Incorrect API access token

{
  "error": "account not found"
}

500: Internal Server Error

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

getDeliveryFunnel

Returns the delivery funnel for a single message, split by channel: audience → sent → errors → deliveries → opened, plus interactions for email broadcasts. Includes a breakdown of where each channel’s audience is lost at each stage.

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

Headers

Name	Required	Description
Authorization	Required	API access token from Pushwoosh Control Panel.

Request body parameters

Name	Required	Type	Description
message_code	Yes	String	Message code obtained from /createMessage API responses.
platforms	No	Array of Integer	Optional platform ID filter.

There is no time-range parameter: the funnel has no time axis, so the server derives the window from the message’s own send and confirmation data (returned as window_from/window_to).

Example request

{
  "message_code": "A444-AAABBBCC-00112233",  // required, message code obtained from /createMessage response
  "platforms": [1, 3, 7]                     // optional, list of platform codes
}

Response fields

Name	Type	Description
channels	array	One entry per channel with data for this message. A channel the message never used is omitted — its absence means “no data”, not zero.
channels[].channel	string	CHANNEL_MOBILE_PUSH (iOS, OSX, Android, Amazon, Huawei), CHANNEL_WEB_PUSH (Safari, Chrome, Firefox), CHANNEL_EMAIL, or CHANNEL_OTHER (SMS, messengers, Wallet, Windows, and other platforms).
channels[].funnel	array	Funnel stages for this channel, always in this order: STAGE_AUDIENCE, STAGE_SENT, STAGE_ERRORS, STAGE_DELIVERIES, STAGE_OPENED, and — for email broadcasts only, not transactional messages — STAGE_INTERACTIONS.
channels[].funnel[].stage	string	Funnel stage name.
channels[].funnel[].count	string	Total count for the stage.
channels[].funnel[].pieces	array	Breakdown of count into categories. Empty on STAGE_ERRORS, which carries errors instead. A category with a zero count is omitted rather than returned as 0.
channels[].funnel[].pieces[].kind	string	How the piece relates to the stage total: KIND_PASSED (moved on to the next stage) or KIND_REASON (dropped out for this reason). Every piece is a summand — a stage’s pieces always add up to its count.
channels[].funnel[].pieces[].category	string	Breakdown category, e.g. INVALID_TOKEN, FREQUENCY_CAPPING, ELIGIBLE_AUDIENCE — see the stage table below.
channels[].funnel[].pieces[].count	string	Count for this category.
channels[].funnel[].pieces[].platforms	array	Per-platform breakdown of this category: { "platform": <id>, "count": "<n>" }. A platform with nothing to report is omitted, not returned as 0.
channels[].funnel[].errors	array	STAGE_ERRORS only, in place of pieces: one row per drop-out category (category, count, platforms) — same shape as a piece, minus kind.
channels[].funnel[].platforms	array	Per-platform breakdown of the stage’s own count.
channels[].deliveries_form	string	Which breakdown STAGE_DELIVERIES carries: DELIVERIES_FORM_PER_DEVICE (three rows, alert state known) or DELIVERIES_FORM_BASIC (two rows, alert state unknown).
channels[].basic_form_reason	string	Set only when deliveries_form is DELIVERIES_FORM_BASIC: BASIC_FORM_REASON_RETENTION (message older than the row-level log retains), BASIC_FORM_REASON_UNAVAILABLE (no per-device data for this account), BASIC_FORM_REASON_NO_DELIVERIES (nothing accepted yet), or BASIC_FORM_REASON_NOT_APPLICABLE (this channel has no alert state — not a degradation).
channels[].confirmed_deliveries	object	{ "count": "<n>", "platforms": [...] } — unique devices that confirmed delivery, independent of deliveries_form. confirmed_deliveries is not clamped to STAGE_DELIVERIES.count, so it can drift slightly past that total; use confirmed_deliveries for a continuous delivery trend across messages of different ages.
window_from, window_to	string (RFC 3339 date-time)	The time window the funnel was actually computed over, derived from the message’s own data.
funnel_state	string	FUNNEL_STATE_READY (channels populated), FUNNEL_STATE_NO_EVENTS (nothing has happened for this message yet — channels is empty), or FUNNEL_STATE_EXPIRED (message older than 365 days, statistics no longer stored — channels is empty).

Funnel stages

Stage	Applies to	count means	pieces / errors
STAGE_AUDIENCE	all channels	Taken into processing.	KIND_PASSED ELIGIBLE_AUDIENCE; KIND_REASON: FREQUENCY_CAPPING, CONTROL_GROUP (all channels), UNSUBSCRIBED, BOUNCED, COMPLAINT, FILTERED_BY_CATEGORY (email only)
STAGE_SENT	all channels	Accepted by the gateway/provider (ACCEPTED_BY_GATEWAY).	none — the stage is entirely the accepted total; rejections show up under STAGE_ERRORS instead
STAGE_ERRORS	all channels	Rejected before reaching the recipient.	errors[], not pieces: INTERNAL_ERROR, INVALID_TOKEN, NO_TOKEN, NO_DEVICE, PLATFORM_DISABLED, QUOTA_EXCEEDED, INVALID_CONTENT, INVALID_CONFIGURATION, PROVIDER_ERROR (uncategorized)
STAGE_DELIVERIES	all channels	Accepted sends to confirm — how many there were, not how many confirmed.	Per-device form: KIND_PASSED DISPLAYABLE_CONFIRMED; KIND_REASON: DISPLAYABLE_NO_CONFIRMATION, ALERTS_DISABLED. Basic form: KIND_PASSED CONFIRMED_BY_DEVICE; KIND_REASON NO_CONFIRMATION
STAGE_OPENED	all channels	Unique devices/addresses that opened.	Email only, and only while the message is under 60 days old: KIND_PASSED OPENED_BY_RECIPIENT; KIND_REASON: MACHINE_OPENS_ONLY (automated opens, e.g. mailbox preview clients), OPEN_TYPE_UNKNOWN. Other channels, and email past 60 days: no pieces.
STAGE_INTERACTIONS	email broadcasts only (not transactional messages)	What the recipient did with the email.	KIND_PASSED CLICKED_ONLY; KIND_REASON: CLICKED_AND_UNSUBSCRIBED, CLICKED_AND_COMPLAINED, UNSUBSCRIBED_WITHOUT_CLICK, COMPLAINED_WITHOUT_CLICK

Response example

{
  "channels": [
    {
      "channel": "CHANNEL_EMAIL",
      "funnel": [
        {
          "stage": "STAGE_AUDIENCE",
          "count": "600000",
          "pieces": [
            { "kind": "KIND_PASSED", "category": "ELIGIBLE_AUDIENCE", "count": "580000" },
            { "kind": "KIND_REASON", "category": "UNSUBSCRIBED", "count": "14000" },
            { "kind": "KIND_REASON", "category": "BOUNCED", "count": "6000" }
          ]
        },
        {
          "stage": "STAGE_SENT",
          "count": "560000",
          "pieces": []
        },
        {
          "stage": "STAGE_ERRORS",
          "count": "20000",
          "errors": [
            { "category": "INVALID_TOKEN", "count": "18000" },
            { "category": "PROVIDER_ERROR", "count": "2000" }
          ]
        },
        {
          "stage": "STAGE_DELIVERIES",
          "count": "560000",
          "pieces": [
            { "kind": "KIND_PASSED", "category": "CONFIRMED_BY_DEVICE", "count": "540000" },
            { "kind": "KIND_REASON", "category": "NO_CONFIRMATION", "count": "20000" }
          ]
        },
        {
          "stage": "STAGE_OPENED",
          "count": "30514",
          "pieces": [
            { "kind": "KIND_PASSED", "category": "OPENED_BY_RECIPIENT", "count": "26102" },
            { "kind": "KIND_REASON", "category": "MACHINE_OPENS_ONLY", "count": "4412" }
          ]
        },
        {
          "stage": "STAGE_INTERACTIONS",
          "count": "1980",
          "pieces": [
            { "kind": "KIND_PASSED", "category": "CLICKED_ONLY", "count": "1820" },
            { "kind": "KIND_REASON", "category": "UNSUBSCRIBED_WITHOUT_CLICK", "count": "140" },
            { "kind": "KIND_REASON", "category": "CLICKED_AND_COMPLAINED", "count": "20" }
          ]
        }
      ],
      "deliveries_form": "DELIVERIES_FORM_BASIC",
      "basic_form_reason": "BASIC_FORM_REASON_NOT_APPLICABLE",
      "confirmed_deliveries": { "count": "540000" }
    },
    {
      "channel": "CHANNEL_MOBILE_PUSH",
      "funnel": [
        {
          "stage": "STAGE_DELIVERIES",
          "count": "168316",
          "pieces": [
            { "kind": "KIND_PASSED", "category": "DISPLAYABLE_CONFIRMED", "count": "89570" },
            { "kind": "KIND_REASON", "category": "DISPLAYABLE_NO_CONFIRMATION", "count": "78746" }
          ]
        },
        { "stage": "STAGE_OPENED", "count": "30514", "pieces": [] }
      ],
      "deliveries_form": "DELIVERIES_FORM_PER_DEVICE",
      "confirmed_deliveries": { "count": "91240" }
    }
  ],
  "window_from": "2026-08-01T00:00:00Z",
  "window_to": "2026-08-04T00:00:00Z",
  "funnel_state": "FUNNEL_STATE_READY"
}

Response codes and examples

200: OK

{
  "channels": [],
  "funnel_state": "FUNNEL_STATE_NO_EVENTS"
}

400: Bad Request

{
  "error": "message_code must be set"
}

401: Unauthorized

{
  "error": "account not found"
}

404: Not Found

{
  "error": "message not found"
}

500: Internal Server Error

Note

Where a stage carries pieces (or, on STAGE_ERRORS, errors), they are disjoint and always add up to that stage’s count. Some stages have no breakdown at all — STAGE_SENT always, STAGE_OPENED outside email or past the 60-day window — and their count is just a total, with pieces returned empty. A stage with no data for a channel is omitted rather than returned empty.

Note

confirmed_deliveries is included for CHANNEL_EMAIL regardless of account settings. For other channels, it’s included only for accounts with delivery-statistics visibility enabled.

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", "inbox_delivered", "inbox_read", "inbox_opened", "inbox_deleted".
platforms	No	Array	Array of target platforms to filter results. Possible values: "ios", "android", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "huawei_android".

Example request

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

Important

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.

Response codes and examples

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

Note

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

Tip

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

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

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

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

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

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