消息统计

messages:list

显示已发送消息的列表。

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

Headers

名称	必填	描述
`Authorization`	是	Server API token。必须按以下格式提供：`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"`）。
`campaign`	否	String	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。
`messages_ids`	否	Array	从 Message History（消息历史记录）中获得的消息 ID。
`params`	否	Object	指定是否显示消息详情和指标。设置 `with_details: true` 以在响应中包含 `"details"` 对象，设置 `with_metrics: true` 以包含 `"metrics"` 对象。
`application`	是	String	Pushwoosh 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
      }]
    }
  }]
}

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

{
  "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。	是
`platforms`	[int]	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。

请求体参数

名称	必填	类型	描述
`message_id`	否	Integer	通过从消息历史记录中获得的 Message ID 选择消息事件。例如：`12345678900`。
`message_code`	否	String	通过从 `/createMessage` API 响应中获得的 Message code 选择消息事件。例如：`"A444-AAABBBCC-00112233"`。
`campaign_code`	否	String	通过消息 payload 中指定的 Campaign code 选择消息事件。例如：`"AAAAA-XXXXX"`。
`hwid`	否	String or Array	通过 HWID (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 选择消息事件。有关更多详细信息，请参阅 `/registerUser`。
`application_code`	是	String	通过 Pushwoosh 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"`。

请求示例

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

响应代码和示例

{
  "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 access token。

请求体参数

名称	必填	类型	描述
`date_range`	否	Object	定义报告期。包含 `date_from` 和 `date_to`。
`filters`	是	Object	电子邮件过滤器。
`application`	是	String	Pushwoosh Application code（或者，指定 `campaign`、`messages_ids` 或 `message_codes`）。
`messages_codes`	是	Array	Message codes（或者，指定 `application`、`campaign` 或 `messages_ids`）。
`campaign`	是	String	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	电子邮件内容的唯一标识符。
`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",               // 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 数组中传递。
   }
}'

响应代码和示例

{
  "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 access token。

请求体参数

名称	必填	类型	描述
`date_range`	否	Object	定义报告期。包含 `date_from` 和 `date_to`。
`filters`	是	Object	电子邮件过滤器。
`application`	是	String	Pushwoosh Application code（或者，指定 `campaign`、`messages_ids` 或 `message_codes`）。
`messages_codes`	是	Array	Message codes（或者，指定 `application`、`campaign` 或 `messages_ids`）。
`campaign`	是	String	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	电子邮件内容的唯一标识符。
`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",             // 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
}'

响应代码和示例

{
  "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 Access Token（API 访问令牌）处理。

请求体参数

参数名称	类型	描述	必填
`application`	string	Pushwoosh Application code	是
`message_code`	string	Message code。	如果未提供 `date range` 或 `campaign`，则为必填项
`campaign`	string	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
  }]
}