消息统计

messages:list

显示已发送消息的列表。

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

标头

名称	是否必需	描述
`Authorization`	是	服务器 API 令牌。必须以下列格式提供：`Authorization: Api <Server Key>`。

请求正文参数

名称	是否必需	类型	描述
`platforms`	否	Array	消息平台。可能的值：`"IOS"`、`"ANDROID"`、`"OSX"`、`"WINDOWS"`、`"AMAZON"`、`"SAFARI"`、`"CHROME"`、`"FIREFOX"`、`"IE"`、`"EMAIL"`、`"HUAWEI_ANDROID"`、`"SMS"`。
`date_range`	否	Object	报告期，按消息创建日期筛选。`date_from` 和 `date_to` 必须遵循 `YYYY-MM-DD` 格式（例如 `“2000-01-01”`）；两天都完全包含在内，因此将 `date_from` 和 `date_to` 设置为同一日期会返回该整天的数据。日期以 UTC 解释，而不是您账户的时区。
`campaign`	否	String	营销活动代码
`filters`	是	Object	消息筛选器。
`source`	否	String	消息来源。例如：`AB_TEST`、`API`、`AUTO_PUSH`、`CP`、`CSV`、`CUSTOMER_JOURNEY`、`EMAIL_API`、`EMAIL_CP`、`GEO_ZONE`、`PUSH_ON_EVENT`、`RSS`。
`messages_codes`	否	Array	从 `/createMessage` API 响应中获取的消息代码。
`messages_ids`	否	Array	从消息历史记录中获取的消息 ID
`params`	否	Object	指定是否显示消息详情和指标。设置 `with_details: true` 以在响应中包含 `“details”` 对象，设置 `with_metrics: true` 以包含 `“metrics”` 对象。
`application`	是	String	Pushwoosh 应用程序代码。
`per_page`	否	Integer	每页结果数，`1` 到 `499`。省略该参数以获取默认的 500 个结果的页面大小；明确传递 `500` 或更多将被拒绝并返回 `400`。
`page`	否	Integer	用于分页的从零开始的页码。请参阅下面的深度分页限制。

请求示例

{
    "filters": {
      "platforms": [],                  // IOS、ANDROID、OSX、WINDOWS、AMAZON、SAFARI、CHROME、FIREFOX、IE、EMAIL、HUAWEI_ANDROID、SMS
      "date_range": {
        "date_from": "string",          // 必需格式：2000-01-01
        "date_to": "string"             // 必需格式：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",             // 营销活动代码
      "messages_ids": [],               // 消息 ID
      "messages_codes": [],             // 消息代码
      "application": "string"           // Pushwoosh 应用程序代码
    },
    "params": {
      "with_details": true,             // 将消息详情添加到响应中（“details”对象）
      "with_metrics": true              // 将消息指标添加到响应中（“metrics”对象）
    },
    "per_page": 20,                     // <= 499
    "page": 0
}

响应代码和示例

{
  "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": [               // 标签条件 (参见 /developer/api-reference/messages-api/#tag-conditions)
            TAG_CONDITION1,
            TAG_CONDITION2,
            ...,
            TAG_CONDITIONN
          ],
          "conditions_operator": "AND", // 条件数组的逻辑运算符；可能的值：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": [              // 标签条件 (参见 Messages-api - tag-conditions)
          TAG_CONDITION1,
          TAG_CONDITION2,
          ...,
          TAG_CONDITIONN
        ],
        "conditions_operator": "AND" // 条件数组的逻辑运算符；可能的值：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 跨度超过 30 天：

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

page × per_page 超过深度分页限制：

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

{
  "error": "account not found"
}

totalsByIntervals

根据消息代码返回指标和转化数据，按小时汇总。

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

授权

授权通过请求标头中的 API 访问令牌处理。

请求正文参数

参数名称	类型	描述	是否必需
`message_code`	string	从 `/createMessage` API 响应中获取的消息代码。	是
`platforms`	[int]	平台	否

请求示例

{
  "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // 必需。唯一消息标识符
  "platforms": [1, 3, 7, 10, 11, 12]          // 可选。平台代码列表
}

响应字段

名称	类型	描述
`metrics`	array	包含消息指标的数组
`timestamp`	string	指标的时间。
`platform`	int	平台代码（例如 iOS、Android）。
`sends`	string	已发送消息数。
`opens`	string	已打开消息数。
`deliveries`	string	已送达消息数。
`inbox_opens`	string	收件箱打开次数。
`unshowable_sends`	string	操作系统设置中通知已关闭的设备接受的消息数。不显示横幅，但消息仍会到达应用，如果发送时启用了保存消息到收件箱，则会出现在消息收件箱中。计为成功发送，而非错误。
`errors`	string	错误数。
`conversion`	object	包含转化数据
`sends`	string	已发送消息总数。
`opens`	string	已打开消息总数。
`events`	array	包含事件及其统计信息的数组
`name`	string	事件名称（例如，添加到购物车）。
`hits`	string	点击次数。
`conversion`	float	相对于打开的转化率。
`revenue`	float	收入（仅适用于带有 `__amount` 和 `__currency` 属性的事件）。

响应示例

{
  "metrics": [{
    "timestamp": "2024-08-03 15:00:00",  // 指标的时间戳，格式为 "YYYY-MM-DD HH:MM:SS"
    "platform": 3,                       // 平台代码
    "sends": "55902",                    // 已发送消息数
    "opens": "382",                      // 已打开消息数
    "deliveries": "22931",               // 已送达消息数
    "inbox_opens": "0",                  // 收件箱中已打开消息数
    "unshowable_sends": "2",             // 发送到通知已关闭的设备，不显示横幅
    "errors": "0"                        // 遇到的错误数
  }],
  "conversion": {
    "sends": "55902",                    // 已发送消息总数
    "opens": "772",                      // 已打开消息总数
    "events": [{
      "name": "cart_add",                // 事件名称
      "hits": "96",                      // 事件的点击次数
      "conversion": 0.12,                // 相对于打开的转化率
      "revenue": 0                       // 事件产生的收入（仅适用于带有金额/货币属性的事件）
    }]
  }
}

getMessageLog

显示有关已发送消息的详细信息。

POST https://api.pushwoosh.com/api/v2/statistics/getMessageLog

标头

名称	是否必需	描述
`Authorization`	必需	来自 Pushwoosh 控制面板的 API 访问令牌。

请求正文参数

名称	是否必需	类型	描述
`message_id`	否	Integer	通过从消息历史记录中获取的消息 ID 选择消息事件。示例：`12345678900`。
`message_code`	否	String	通过从 `/createMessage` API 响应中获取的消息代码选择消息事件。示例：`"A444-AAABBBCC-00112233"`。
`campaign_code`	否	String	通过在消息负载中指定的营销活动代码选择消息事件。示例：`"AAAAA-XXXXX"`。
`hwid`	否	String 或 Array	通过 HWID (硬件 ID) 或 HWID 数组选择消息事件。
`date_from`	如果未提供 `message_id`、`message_code` 或 `campaign_code`，则为必需	Datetime	用于筛选消息的开始日期。格式：`"YYYY-MM-DD HH:MM:SS"`。示例：`"2000-01-25 00:00:00"`。
`date_to`	如果未提供 `message_id`、`message_code` 或 `campaign_code`，则为必需	Datetime	用于筛选消息的结束日期。格式：`"YYYY-MM-DD HH:MM:SS"`。示例：`"2000-01-26 00:00:00"`。
`limit`	否	Integer	单个响应中返回的最大消息事件数。最大值：`100000`。
`pagination_token`	否	String	从上一个 `/getMessageLog` 响应中获取的分页令牌。用它来检索其他结果。
`user_id`	否	String	通过自定义用户 ID选择消息事件。有关更多详细信息，请参阅 `/registerUser`。
`application_code`	是	String	通过 Pushwoosh 应用程序代码选择消息事件
`actions`	否	Array	按特定消息操作筛选结果。可能的值：`"sent"`、`"delivered"`、`"opened"`、`"reject"`、`"create"`、`"inbox_delivered"`、`"inbox_read"`、`"inbox_opened"`、`"inbox_deleted"`。默认情况下，`"create"` 事件会从响应中排除。在此数组中包含 `"create"` 以查看它们。`"delivered"` 事件另外要求在账户上启用送达统计。
`platforms`	否	Array	用于筛选结果的目标平台数组。可能的值：`"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`	否	String	按消息流筛选结果。`"all"`（如果省略则为默认值）返回所有内容，`"broadcast"` 仅返回群发消息 (`message_id != 0`)，`"transactional"` 仅返回 `message_id = 0` 的消息，包括从 Customer Journey 发送的消息。

请求示例

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",  // 可选，用于分页的令牌
   "limit": 1000,                                  // 可选，单个响应的最大条目数
   "application_code": "XXXXX-XXXXX",              // Pushwoosh 应用代码
   "message_code": "A444-AAABBBCC-00112233",       // 可选，从 /createMessage 请求获取的消息代码
   "message_id": 1234567890,                       // 可选，从 Pushwoosh 控制面板获取的消息 ID
   "campaign_code": "AAAAA-XXXXX",                 // 可选，要获取日志的营销活动代码
   "hwid": "aaazzzqqqqxxx",                        // 可选，消息所针对的特定设备的硬件 ID
   "user_id": "user_123",                          // 可选，消息所针对的用户的 ID
   "date_from": "2000-01-25 00:00:00",             // 可选，统计周期的开始
   "date_to": "2000-02-10 23:59:59",               // 可选，统计周期的结束
   "actions": ["opened", "inbox_opened"],          // 可选，用于结果过滤。可能的值："sent"、"delivered"、"opened"、"reject"、"create"、"inbox_delivered"、"inbox_read"、"inbox_opened"、"inbox_deleted"。响应将包括所有具有指定操作的消息。
   "platforms": ["ios", "chrome"],                 // 可选，用于结果过滤，仅限小写。可能的值："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"                     // 可选，“all”（默认）、“broadcast”（message_id != 0）或“transactional”（message_id = 0，包括 Customer Journey 发送）
}'

响应代码和示例

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

data 中的每个条目还带有 error_reason（字符串，当 status 为 "failed" 时填充失败原因）和一个可选的 payload（字符串）。

响应页面返回的结果可能比请求的 limit 少。这本身并不意味着导出已完成。

电子邮件统计

linksInteractions

显示电子邮件中链接点击的统计数据

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

标头

名称	是否必需	描述
`Authorization`	是	来自 Pushwoosh 控制面板的 API 访问令牌。

请求正文参数

名称	是否必需	类型	描述
`date_range`	否	Object	定义报告期。包含 `date_from` 和 `date_to`。
`filters`	是	Object	电子邮件筛选器。
`application`	是	String	Pushwoosh 应用程序代码（或者，指定 `campaign`、`messages_ids` 或 `message_codes`）。
`messages_codes`	是	Array	消息代码（或者，指定 `application`、`campaign` 或 `messages_ids`）。
`campaign`	是	String	营销活动代码（或者，指定 `application`、`messages_ids` 或 `message_codes`）。
`messages_ids`	是	Array	消息 ID（或者，指定 `application`、`campaign` 或 `message_codes`）。
`link_template`	如果指定了 `application` 或 `campaign`，则为必需。	String	按关键字筛选电子邮件链接交互。只有 URL 中包含指定文本的链接才会在 API 响应中返回。例如，如果您的电子邮件包含 `https://example.com/news` 和 `https://example.com/shop` 等链接，设置 `"link_template": "shop"` 将仅返回 `https://example.com/shop` 的交互。
`email_content_code`	否	String	电子邮件内容的唯一标识符。
`params`	否	Object	定义其他响应选项。包括 `with_full_links`，它会添加一个包含统计信息的完整链接列表。

请求示例

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",           // 必需格式：2000-01-01
         "date_to": "string"              // 必需格式：2000-01-01
      },
      "campaign": "string",               // 营销活动代码（您可以指定 application、messages_ids 或 message_codes）
      "application": "string",            // 应用程序代码（您可以指定 campaign、messages_ids 或 message_codes）
      "messages_ids": [],                 // 消息 ID（您可以指定 application、campaign 或 message_codes）
      "messages_codes": [],               // 消息代码（您可以指定 application、campaign 或 message_ids）
      "link_template": "string",          // 链接模板（如果指定了 application 或 campaign 则为必需）
      "email_content_code": "string"      // 电子邮件内容的唯一标识符。
   },
   "params": {
      "with_full_links": true             // 指定是否显示详细统计信息。一个包含统计信息的完整链接列表将在 full_links 数组中传递。
   }
}'

响应代码和示例

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

显示点击了电子邮件中链接的用户

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

标头

名称	是否必需	描述
`Authorization`	是	来自 Pushwoosh 控制面板的 API 访问令牌。

请求正文参数

名称	是否必需	类型	描述
`date_range`	否	Object	定义报告期。包含 `date_from` 和 `date_to`。
`filters`	是	Object	电子邮件筛选器。
`application`	是	String	Pushwoosh 应用程序代码（或者，指定 `campaign`、`messages_ids` 或 `message_codes`）。
`messages_codes`	是	Array	消息代码（或者，指定 `application`、`campaign` 或 `messages_ids`）。
`campaign`	是	String	营销活动代码（或者，指定 `application`、`messages_ids` 或 `message_codes`）。
`messages_ids`	是	Array	消息 ID（或者，指定 `application`、`campaign` 或 `message_codes`）。
`link_template`	如果指定了 `application` 或 `campaign`，则为必需。	String	按关键字筛选电子邮件链接交互。只有 URL 中包含指定文本的链接才会在 API 响应中返回。例如，如果您的电子邮件包含 `https://example.com/news` 和 `https://example.com/shop` 等链接，设置 `"link_template": "shop"` 将仅返回 `https://example.com/shop` 的交互。
`email_content_code`	否	String	电子邮件内容的唯一标识符。
`page`	否	Integer	用于分页的页码。
`per_page`	否	Integer	每页结果数（≤ 1000）。

请求示例

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",         // 必需格式：2000-01-01
         "date_to": "string"            // 必需格式：2000-01-01
      },
      "campaign": "string",             // 营销活动代码（您可以指定 application、messages_ids 或 message_codes）
      "application": "string",          // 应用程序代码（您可以指定 campaign、messages_ids 或 message_codes）
      "messages_ids": [],               // 消息 ID（您可以指定 application、campaign 或 message_codes）
      "messages_codes": [],             // 消息代码（您可以指定 application、campaign 或 message_ids）
      "link_template": "string",        // 链接模板（如果指定了 application 或 campaign 则为必需）
      "email_content_code": "string"    // 电子邮件内容的唯一标识符。
   },
   "per_page": 100,
   "page": 0
}'

响应代码和示例

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

提供有关电子邮件投诉、软退回和硬退回的数据，包括每次退回的日期、电子邮件地址和原因。

授权

授权通过请求标头中的 API 访问令牌处理。

请求正文参数

参数名称	类型	描述	是否必需
`application`	string	Pushwoosh 应用程序代码	是
`message_code`	string	消息代码。	如果未提供 `date range` 或 `campaign`，则为必需
`campaign`	string	营销活动代码。	如果未提供 `message_code` 或 `date range`，则为必需
`date_from`	string	数据的开始日期，格式为 `YYYY-MM-DDTHH:MM:SS.000Z`（ISO 8601 标准）。	如果未提供 `message_code` 或 `campaign`，则为必需
`date_to`	string	数据的结束日期，格式为 `YYYY-MM-DDTHH:MM:SS.000Z`（ISO 8601 标准）。	如果未提供 `message_code` 或 `campaign`，则为必需
`per_page`	int	每页行数，最多 5000。	是
`page`	int	页码，从零开始。	是
`type`	string	退回类型：Complaint、Softbounce、Hardbounce。	否

请求示例

{
  "application": "XXXXX-XXXXX",               // 必需。Pushwoosh 应用代码
  "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // 如果未提供 campaign 或日期范围，则为必需。
                                              //          唯一消息标识符
  "campaign": "XXXXX-XXXXX",                  // 如果未提供 message_code 或日期范围，则为必需。
                                              //          营销活动代码
  "date_from": "2024-07-20T00:00:00.000Z",    // 如果未提供 message_code 或 campaign，则为必需。
                                              //          开始日期，ISO 8601 格式 "YYYY-MM-DDTHH:MM:SS.SSSZ"
  "date_to": "2024-07-20T00:00:00.000Z",      // 如果未提供 message_code 或 campaign，则为必需。
                                              //          结束日期，ISO 8601 格式 "YYYY-MM-DDTHH:MM:SS.SSSZ"
  "per_page": 1000,                           // 必需。每页结果数，最多 5000
  "page": 5,                                  // 可选。页码，从零开始
  "type": "Softbounce"                        // 可选。退回类型：Complaint、Softbounce、Hardbounce
}

响应字段

字段名称	类型	描述
`total`	int	总行数。
`bounced_emails`	array	退回电子邮件详情的数组。
├── `email`	string	退回的电子邮件地址。
├── `date`	string	退回日期（格式：`YYYY-MM-DDTHH:MM:SS.000Z`）。
├── `reason`	string	退回原因。
└── `type`	string	退回类型：Complaint、Softbounce、Hardbounce。

响应示例

{
  "total": 25,                             // 总行数。
  "bounced_emails": [{
    "email": "example@example.com",        // 退回的电子邮件地址
    "date": "2024-07-20T00:00:00.000Z",    // 退回日期，ISO 8601 格式
    "reason": "Invalid recipient address", // 退回原因
    "type": "Hardbounce"                   // 退回类型：Complaint、Softbounce、Hardbounce
  }]
}