消息统计

messages:list

显示已发送消息的列表。

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

Headers

名称	是否必需	描述
`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` 设置为同一天将返回那一整天的数据。
`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	事件的名称（例如，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 访问令牌。

请求正文参数

名称	是否必需	类型	描述
`message_id`	否	Integer	按从消息历史记录中获取的消息 ID 选择消息事件。示例：`12345678900`。
`message_code`	否	String	按从 `/createMessage` API 响应中获取的消息代码选择消息事件。示例：`"A444-AAABBBCC-00112233"`。
`campaign_code`	否	String	按消息负载中指定的营销活动代码选择消息事件。示例：`"AAAAA-XXXXX"`。
`hwid`	否	String or 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"`、`"inbox_delivered"`、`"inbox_read"`、`"inbox_opened"`、`"inbox_deleted"`。
`platforms`	否	Array	用于筛选结果的目标平台数组。可能的值：`"ios"`、`"android"`、`"osx"`、`"windows"`、`"amazon"`、`"safari"`、`"chrome"`、`"firefox"`、`"ie"`、`"email"`、`"huawei_android"`。

请求示例

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",       // 可选，从 /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"
}'

响应代码和示例

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

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

{
  "error": "account not found"
}

电子邮件统计

linksInteractions

显示电子邮件中链接点击的统计信息

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

Headers

名称	是否必需	描述
`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

Headers

名称	是否必需	描述
`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 或 date range，则为必需。
                                              //          唯一的消息标识符
  "campaign": "XXXXX-XXXXX",                  // 如果未提供 message_code 或 date range，则为必需。
                                              //          营销活动代码
  "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
  }]
}