# 消息统计 ## messages:list 显示已发送消息的列表。 `POST` `https://api.pushwoosh.com/api/v2/messages:list` ##### Headers | 名称
| 必填
| 描述
| |----------------|----------|------------------------------------------------------------------------------------------------------| | `Authorization`| 是 | [Server API token](/zh/developer/api-reference/api-access-token/#server-api-token)。必须按以下格式提供：`Authorization: Api `。 | ##### 请求体参数 | 名称
| 必填
| 类型
| 描述
| |--------------------------------------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------| | `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"`）。 | | `campaign` | 否 | String | [Campaign code](/zh/developer/api-reference/api-identifiers/#campaign-code) | | `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 响应中获得的 [Message codes](/zh/developer/api-reference/api-identifiers/#message-code)。 | | `messages_ids` | 否 | Array | 从 Message History（消息历史记录）中获得的消息 ID。 | | `params` | 否 | Object | 指定是否显示消息详情和指标。设置 `with_details: true` 以在响应中包含 `"details"` 对象，设置 `with_metrics: true` 以包含 `"metrics"` 对象。 | | `application` | 是 | String | [Pushwoosh Application code](/zh/developer/api-reference/api-identifiers/#application-code)。 | | `per_page` | 否 | Integer | 每页结果数 (≤ 1000)。 | | `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", // Campaign code "messages_ids": [], // Message IDs "messages_codes": [], // Message codes "application": "string" // Pushwoosh application code }, "params": { "with_details": true, // 将消息详情添加到响应中（"details" 对象） "with_metrics": true // 将消息指标添加到响应中（"metrics" 对象） }, "per_page": 20, // <= 1000 "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 }] } }] } ``` ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` ```json { "error": "account not found" } ```
## totalsByIntervals 返回基于消息代码的指标和转化数据，按小时聚合。 **POST** `https://api.pushwoosh.com/api/v2/statistics/messages/totalsByIntervals` ##### 授权 授权通过请求头中的 API Access Token（API 访问令牌）处理。 ##### 请求体参数 | 参数名称
| 类型
| 描述 | 必填 | |----------------|--------|-----------------------------|----------| | `message_code` | string | 从 `/createMessage` API 响应中获得的 [Message code](/zh/developer/api-reference/api-identifiers/#message-code)。 | 是 | | `platforms` | [int] | [Platforms](/zh/developer/api-reference/messages-api/api-prerequisites/#platforms) | 否 | ##### 请求示例 ``` { "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 | 事件名称（例如 cart add）。 | | `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 // 事件产生的收入（仅适用于具有 amount/currency 属性的事件） }] } } ``` ## getMessageLog 显示有关已发送消息的详细信息。 `POST` `https://api.pushwoosh.com/api/v2/statistics/getMessageLog` ##### Headers | 名称
| 必填
| 描述
| |-----------------|----------|----------------------------------------------------------------------------------------------------------------------------| | `Authorization` | 是 | 来自 Pushwoosh 控制面板的 [API access token](/zh/developer/api-reference/api-access-token/)。 | ##### 请求体参数 | 名称
| 必填
| 类型
| 描述
| |--------------------|------------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `message_id` | 否 | Integer | 通过从消息历史记录中获得的 Message ID 选择消息事件。例如：`12345678900`。 | | `message_code` | 否 | String | 通过从 `/createMessage` API 响应中获得的 [Message code](/zh/developer/api-reference/api-identifiers/#message-code) 选择消息事件。例如：`"A444-AAABBBCC-00112233"`。 | | `campaign_code` | 否 | String | 通过消息 payload 中指定的 [Campaign code](/zh/developer/api-reference/api-identifiers/#campaign-code) 选择消息事件。例如：`"AAAAA-XXXXX"`。 | | `hwid` | 否 | String or Array | 通过 [HWID (Hardware ID)](/zh/developer/api-reference/api-identifiers/#hardware-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 | 通过自定义 [User ID](/zh/developer/api-reference/api-identifiers/#user-id) 选择消息事件。有关更多详细信息，请参阅 `/registerUser`。 | | `application_code` | 是 | String | 通过 [Pushwoosh Application code](/zh/developer/api-reference/api-identifiers/#application-code) 选择消息事件。 | | `actions` | 否 | Array | 按特定消息动作过滤结果。可能的值：`"sent"`, `"delivered"`, `"opened"`, `"inbox_delivered"`, `"inbox_read"`, `"inbox_opened"`, `"inbox_deleted"`。 | | `platforms` | 否 | Array | 过滤结果的目标平台数组。可能的值：`"ios"`, `"android"`, `"osx"`, `"windows"`, `"amazon"`, `"safari"`, `"chrome"`, `"firefox"`, `"ie"`, `"email"`, `"huawei_android"`。 | ##### 请求示例 ```shell 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 application code "message_code": "A444-AAABBBCC-00112233", // 可选，从 /createMessaage 请求中获得的消息代码 "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", "opened", "delivered", "inbox_delivered", "inbox_read", "inbox_opened", "inbox_deleted"。响应将包含具有指定动作的所有消息。 "platforms": ["ios", "chrome"] // 可选，用于结果过滤。可能的值："ios", "android", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "huawei android" }' ```
响应代码和示例 ```json { "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" }] } ``` ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` ```json { "error": "account not found" } ```
## 电子邮件统计 ### linksInteractions 显示电子邮件中链接点击的统计数据 `POST` `https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractions` ##### Headers | 名称
| 必填
| 描述 | |-----------------|----------|-------------------------------------------------------------------------------------------------------| | `Authorization` | 是 | 来自 Pushwoosh 控制面板的 [API access token](/zh/developer/api-reference/api-access-token/)。 | ##### 请求体参数 | 名称
| 必填
| 类型 | 描述 | |--------------------|----------|--------|------------------------------------------------------------------------------------------------------| | `date_range` | 否 | Object | 定义报告期。包含 `date_from` 和 `date_to`。 | | `filters` | 是 | Object | 电子邮件过滤器。 | | `application` | 是 | String | [Pushwoosh Application code](/zh/developer/api-reference/api-identifiers/#application-code)（或者，指定 `campaign`、`messages_ids` 或 `message_codes`）。 | | `messages_codes` | 是 | Array | [Message codes](/zh/developer/api-reference/api-identifiers/#message-code)（或者，指定 `application`、`campaign` 或 `messages_ids`）。 | | `campaign` | 是 | String | [Campaign code](/zh/developer/api-reference/api-identifiers/#campaign-code)（或者，指定 `application`、`messages_ids` 或 `message_codes`）。 | | `messages_ids` | 是 | Array | Message IDs（或者，指定 `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 | [电子邮件内容的唯一标识符](/zh/developer/api-reference/api-identifiers/#email-content-code)。 | | `params` | 否 | Object | 定义额外的响应选项。包括 `with_full_links`，它添加了带有统计信息的完整链接列表。 | ##### 请求示例 ```shell 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", // Campaign code（您可以指定 application、messages_ids 或 message_codes 代替） "application": "string", // Application code（您可以指定 campaign、messages_ids 或 message_codes 代替） "messages_ids": [], // Message IDs（您可以指定 application、campaign 或 message_codes 代替） "messages_codes": [], // Message codes（您可以指定 application、campaign 或 message_ids 代替） "link_template": "string", // Link template（如果指定了 application 或 campaign，则为必填项） "email_content_code": "string" // 电子邮件内容的唯一标识符。 }, "params": { "with_full_links": true // 指定是否显示详细统计信息。带有统计信息的完整链接列表将在 full_links 数组中传递。 } }' ``` ##### 响应代码和示例 ```json { "items": [{ "template": "string", "link": "string", "title": "string", "clicks": 0, "full_links": [{ "full_link": "string", "clicks": 0 }] }] } ``` ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` ```json { "error": "account not found" } ``` ### linksInteractionsDevices 显示点击了电子邮件中链接的用户 `POST` `https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractionsDevices` ##### Headers | 名称
| 必填
| 描述 | |-----------------|----------|------------------------------------------------------------------------------------------------------| | `Authorization` | 是 | 来自 Pushwoosh 控制面板的 [API access token](/zh/developer/api-reference/api-access-token/)。 | ##### 请求体参数 | 名称
| 必填
| 类型 | 描述 | |--------------------|----------|---------|------------------------------------------------------------------------------------------------------| | `date_range` | 否 | Object | 定义报告期。包含 `date_from` 和 `date_to`。 | | `filters` | 是 | Object | 电子邮件过滤器。 | | `application` | 是 | String | [Pushwoosh Application code](/zh/developer/api-reference/api-identifiers/#application-code)（或者，指定 `campaign`、`messages_ids` 或 `message_codes`）。 | | `messages_codes` | 是 | Array | [Message codes](/zh/developer/api-reference/api-identifiers/#message-code)（或者，指定 `application`、`campaign` 或 `messages_ids`）。 | | `campaign` | 是 | String | [Campaign code](/zh/developer/api-reference/api-identifiers/#campaign-code)（或者，指定 `application`、`messages_ids` 或 `message_codes`）。 | | `messages_ids` | 是 | Array | Message IDs（或者，指定 `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 | [电子邮件内容的唯一标识符](/zh/developer/api-reference/api-identifiers/#email-content-code)。 | | `page` | 否 | Integer | 分页的页码。 | | `per_page` | 否 | Integer | 每页结果数 (≤ 1000)。 | ##### 请求示例 ```shell 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", // Campaign code（您可以指定 application、messages_ids 或 message_codes 代替） "application": "string", // Application code（您可以指定 campaign、messages_ids 或 message_codes 代替） "messages_ids": [], // Message IDs（您可以指定 application、campaign 或 message_codes 代替） "messages_codes": [], // Message codes（您可以指定 application、campaign 或 message_ids 代替） "link_template": "string", // Link template（如果指定了 application 或 campaign，则为必填项） "email_content_code": "string" // 电子邮件内容的唯一标识符。 }, "per_page": 100, "page": 0 }' ``` ##### 响应代码和示例 ```json { "total": 0, "items": [{ "timestamp": "string", "link": "string", "hwid": "string" }] } ``` ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` ```json { "error": "account not found" } ``` ### bouncedEmails **POST** `https://api.pushwoosh.com/api/v2/statistics/emails/bouncedEmails` 提供有关电子邮件投诉、软退信和硬退信的数据，包括每次退信的日期、电子邮件地址和原因。 ##### 授权 授权通过请求头中的 API Access Token（API 访问令牌）处理。 ##### 请求体参数 | 参数名称 | 类型 | 描述 | 必填 | |----------------|--------|--------------------------------------------------------------------------------------------------|------------------------------------------------| | `application` | string | [Pushwoosh Application code](/zh/developer/api-reference/api-identifiers/#application-code) | 是 | | `message_code` | string | [Message code](/zh/developer/api-reference/api-identifiers/#message-code)。 | 如果未提供 `date range` 或 `campaign`，则为必填项 | | `campaign` | string | [Campaign code](/zh/developer/api-reference/api-identifiers/#campaign-code)。 | 如果未提供 `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 application code "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // 如果未提供 campaign 或 date range，则为必填项。 // 唯一消息标识符 "campaign": "XXXXX-XXXXX", // 如果未提供 message_code 或 date range，则为必填项。 // Campaign 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 }] } ```