异步消息统计导出

exportMessagesStatistics 可将消息历史记录和统计数据导出到服务器上的 CSV 文件中。当 messages:list 无法处理大规模或全账户数据提取时，请使用此方法。

何时使用 export 而非 messages:list

对于有限时间段内的实时分页查询，请使用 messages:list。当结果会超过 messages:list 的深度分页限制 (page × per_page > 100000)，或者目标是获取单个可下载文件而非分页 JSON 时，请使用 exportMessagesStatistics。导出对 date_range 或行数没有限制，因为它将结果流式传输到磁盘上的文件中，而不是将其保存在一个响应中。

导出流程如何运作

1. 使用与 messages:list 相同的筛选器调用 导出。响应会立即返回一个任务标识符 uid，此时文件尚未生成。
2. 使用该 uid 轮询 状态，直到其报告 STATUS_SUCCESS (或 STATUS_FAILED)。
3. 使用相同的 uid 调用 结果，以获取生成的文件 file 和一个即用型 file_url。
4. 下载 文件。直接使用 file_url，或者如果返回的 file_url 为空，请参阅 结果 部分，了解如何从 file 构建 URL。

使用 最近任务 查询应用的近期导出任务，使用 删除 取消任务或提前删除其文件。

方法

导出生命周期有五种方法，外加一个普通的下载端点：

方法	描述
exportMessagesStatistics/export	将导出任务加入队列并返回任务 uid。
exportMessagesStatistics/status	检查任务进度。
exportMessagesStatistics/result	任务完成后返回生成的文件名。
exportMessagesStatistics/lastTasks	列出应用的近期导出任务。
exportMessagesStatistics/delete	在保留期满前取消任务或删除其文件。
下载	按名称下载生成的 CSV 文件。

export

将消息历史记录导出任务加入队列，并立即返回一个任务标识符。

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export

标头

请求需要一个服务器 API 令牌：

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

请求体参数

请求体接受以下字段：

名称	必需	类型	描述
type	是	String	必须是 “TASK_TYPE_EXPORT_MESSAGES_V2”。
export_messages_v2	是	Object	导出参数，如下所述。
export_messages_v2.application_code	见备注	String	Pushwoosh 应用代码。如果未设置 app_group_code，则为必需。
export_messages_v2.app_group_code	见备注	String	应用组代码，导出该组中每个应用的数据。如果未设置 application_code，则为必需。
export_messages_v2.search	否	String	对消息标题和内容进行自由文本搜索。
export_messages_v2.filters	否	Object	消息筛选器，如下所述。省略此项可导出整个账户历史记录。
export_messages_v2.properties	否	Array	要包含在 CSV 中的列，如下所述。

export_messages_v2.filters 接受：

名称	类型	描述
statuses	Array	要包含的消息状态。 可能的值 ”MESSAGE_STATUS_CANCELED" "MESSAGE_STATUS_CREATING" "MESSAGE_STATUS_DONE" "MESSAGE_STATUS_FAIL" "MESSAGE_STATUS_PENDING" "MESSAGE_STATUS_PROCESSING" "MESSAGE_STATUS_WAITING”
platforms	Array	平台代码（数字，例如 iOS 为 1），而不是 messages:list 使用的平台名称字符串。
sent_date	Object	按发送日期筛选的报告周期：{"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}。
created_date	Object	按消息创建日期筛选的报告周期，格式与 sent_date 相同。
created_via	Array	消息来源。 可能的值 ”AB_TEST" "API" "AUTO_PUSH" "CP" "CSV" "CUSTOMER_JOURNEY" "EMAIL_API" "EMAIL_CP" "GEO_ZONE" "PUSH_ON_EVENT" "RSS" "SYSTEM”
segments	Array	消息发送到的筛选器代码。
campaigns	Array	活动代码。与 messages:list 不同，这里接受一个列表，而不是单个代码。
message_id	String (uint64)	单个数字消息 ID，带引号。与 messages:list 不同，导出只接受一个 ID，而不是一个数组。
message_code	String	单个消息代码。

export_messages_v2.properties 选择 CSV 包含哪些列。

可能的值

• "EXPORT_MESSAGE_PROPERTY_ID"
• "EXPORT_MESSAGE_PROPERTY_TIMESTAMP"
• "EXPORT_MESSAGE_PROPERTY_CONTENT"
• "EXPORT_MESSAGE_PROPERTY_TITLE"
• "EXPORT_MESSAGE_PROPERTY_CAMPAIGN_NAME"
• "EXPORT_MESSAGE_PROPERTY_APPLICATIONS"
• "EXPORT_MESSAGE_PROPERTY_STATUS"
• "EXPORT_MESSAGE_PROPERTY_PLATFORMS"
• "EXPORT_MESSAGE_PROPERTY_SOURCE"
• "EXPORT_MESSAGE_PROPERTY_FILTER"
• "EXPORT_MESSAGE_PROPERTY_SUBSCRIPTION_SEGMENTS"
• "EXPORT_MESSAGE_PROPERTY_SENT"
• "EXPORT_MESSAGE_PROPERTY_OPENED"
• "EXPORT_MESSAGE_PROPERTY_ERRORS"
• "EXPORT_MESSAGE_PROPERTY_RECIPIENTS"
• "EXPORT_MESSAGE_PROPERTY_DELIVERED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_DELIVERED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_OPENED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_CLICKS"
• "EXPORT_MESSAGE_PROPERTY_CLICKS"
• "EXPORT_MESSAGE_PROPERTY_UNSUBSCRIBED"

properties 不仅仅是一个筛选器

未在 properties 中列出的属性根本不会出现在文件中，包括基本列（ID、发送日期、内容、状态）。将 properties 留空会生成一个没有列的 CSV。请列出导出应包含的每一列，而不仅仅是您想在默认集基础上添加的指标。

请求示例

{
  "type": "TASK_TYPE_EXPORT_MESSAGES_V2",
  "export_messages_v2": {
    "application_code": "XXXXX-XXXXX",
    "filters": {
      "created_date": {
        "date_from": "2026-01-01",
        "date_to": "2026-06-30"
      },
      "statuses": ["MESSAGE_STATUS_DONE"],
      "platforms": [1, 3]
    },
    "properties": [
      "EXPORT_MESSAGE_PROPERTY_ID",
      "EXPORT_MESSAGE_PROPERTY_TIMESTAMP",
      "EXPORT_MESSAGE_PROPERTY_STATUS",
      "EXPORT_MESSAGE_PROPERTY_PLATFORMS",
      "EXPORT_MESSAGE_PROPERTY_SENT",
      "EXPORT_MESSAGE_PROPERTY_OPENED"
    ]
  }
}

200：成功

{
  "uid": "177458"
}

401：API 访问令牌不正确

{
  "error": "account not found"
}

status

返回导出任务的进度。

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/status

请求体参数

传递由 export 返回的任务标识符：

名称	必需	类型	描述
uid	是	String (int64)	来自 export 响应的任务标识符，例如 "177458"。

请求示例

{
  "uid": "177458"
}

200：成功

{
  "status": "STATUS_SUCCESS",
  "progress": 1
}

status 是 "STATUS_PENDING"、"STATUS_SUCCESS" 或 "STATUS_FAILED" 之一。progress 是一个介于 0 和 1 之间的小数；轮询 status 直到其达到 "STATUS_SUCCESS"，然后再调用 result。

result

任务完成后返回生成的文件名。

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/result

请求体参数

传递由 export 返回的相同任务标识符：

名称	必需	类型	描述
uid	是	String (int64)	来自 export 响应的任务标识符，例如 "177458"。

请求示例

{
  "uid": "177458"
}

200：成功

{
  "export_messages_v2_result": {
    "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv",
    "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}

在 status 报告 "STATUS_SUCCESS" 之前调用 result 会返回一个空结果。file_url 是一个指向账户所在正确数据中心的下载端点的即用型链接——请直接使用它，而不是自己从 file 构建 URL。如果账户的数据中心没有配置基础 URL，file_url 将为空。在这种情况下，只有当账户位于默认的 app.pushwoosh.com 数据中心时，您才能回退到从 file 构建 URL——位于其他数据中心或白标域名的账户无法仅从 file 推导出正确的主机。

lastTasks

列出应用的近期导出任务，最新的在前。

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/lastTasks

请求体参数

每个参数都是可选的筛选器；省略所有参数以列出令牌有权访问的所有任务：

名称	必需	类型	描述
application	否	String	Pushwoosh 应用代码。省略此项可列出令牌有权访问的所有应用的任务。
types	否	Array	限制为特定的任务类型。使用 [“TASK_TYPE_EXPORT_MESSAGES_V2”] 仅查看消息导出。
campaign	否	String	按活动代码筛选。
message_id	否	String (uint64)	按单个数字消息 ID 筛选，带引号。
message_code	否	String	按单个消息代码筛选。
limit	否	Integer	要返回的最大任务数。
timestamp_from	否	String	仅返回在此时间戳（RFC 3339）之后创建的任务。

注意

无论其文件是否在 7 天的文件保留期后被删除，任务都会保留 30 天。lastTasks 仍可能显示一个其 result 不再解析为可下载文件的任务。

请求示例

{
  "application": "XXXXX-XXXXX",
  "types": ["TASK_TYPE_EXPORT_MESSAGES_V2"],
  "limit": 10
}

200：成功

{
  "tasks": [
    {
      "id": "177458",
      "timestamp": "2026-08-13T12:00:00Z",
      "status": "STATUS_SUCCESS",
      "requested_by_user": "user@example.com",
      "export_messages_v2": {
        "application_code": "XXXXX-XXXXX"
      },
      "export_messages_v2_result": {
        "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv",
        "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
      }
    }
  ]
}

delete

在 7 天的保留期满前删除任务及其文件。

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/delete

请求体参数

传递由 export 返回的任务标识符：

名称	必需	类型	描述
uid	是	String (int64)	来自 export 响应的任务标识符，例如 "177458"。

请求示例

{
  "uid": "177458"
}

200：成功

{}

下载

按名称下载由 result 生成的 CSV 文件。

GET https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/<file>

标头

使用与其他方法相同的方式进行身份验证，或依赖于活动的控制面板会话：

名称	必需	描述
Authorization	是	服务器 API 令牌，格式与其他 exportMessagesStatistics 方法相同：Authorization: Api <Server Key>（Api 方案不区分大小写）。没有 Authorization 标头且没有登录的控制面板会话的请求将收到 401 Unauthorized。

将 <file> 替换为 result 响应中的确切 file 值，例如：

https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv

警告

手动构建此 URL 仅适用于位于默认 app.pushwoosh.com 数据中心的账户。位于其他数据中心（OVB 为 app.wavesend.ru，IAD 为 app.pushwoosh.us）或白标域名的账户需要不同的主机，并且无法仅从 file 推导出。请改用 result 或 lastTasks 中的 file_url，因为它已经指向了账户的正确主机。如果 file_url 返回为空，请参阅 result 部分的处理方法。

该文件是一个 CSV，包含在 properties 中选择的列。导出完成后，文件将保留 7 天，之后清理作业会将其删除，URL 将不再可用。

Message recipients export

相同的 export、status、result、lastTasks、delete 和 download 方法也可以导出某条消息的各个接收者。请使用 "type": "TASK_TYPE_EXPORT_MESSAGE_RECIPIENTS" 和 export_message_recipients 对象，而不是 export_messages_v2。

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export

与 Customer Journey 的 Holdout Split 不同

此方法导出的是某条消息排除的接收者。Customer Journey 的 Holdout Split 节点是另一种机制：它会在发送任何消息之前，将用户从 journey 的其余部分中排除，其 exportJourneyPointUsers 任务（使用相同的 export/status/result 方法，但 type 不同）报告的是分支成员，而不是发送结果。

export_message_recipients 请求字段

名称	必需	类型	描述
message_id	见备注	String (uint64)	单个数字消息 ID。如果未设置 campaign，则为必需。
campaign	见备注	String	单个活动代码。如果未设置 message_id，则为必需。同时设置两者时，只会筛选出该消息在此活动中的行。
application	是	String	消息所属的应用代码。
type	是	String	要导出哪类接收者。可选值："sends"、"deliveries"、"opens"、"holdout"（见下文）。
date_from / date_to	否	String (date-time)	将行限制在此时间窗口内。同时省略两者则导出该消息的完整历史记录。

如果同时省略 message_id 和 campaign，或省略 application，请求会失败，并返回指明缺失字段的错误。来自其他账户的 message_id 会失败并返回 NotFound: message not found，该检查在导出运行之前进行。属于同一账户中其他应用的 message_id 或 campaign 不会被拒绝，但不会匹配到任何行，下载的 CSV 只有表头。

type 用于选择接收者集合：

值	返回的行
"sends"	消息已接受发送的每个接收者。
"deliveries"	sends 中提供商已确认送达的接收者。
"opens"	sends 中打开了消息的接收者。
"holdout"	此消息排除的接收者，不包括其他任何消息排除的接收者。不会向他们发送任何内容。账户级对照组或消息自身的 holdout_percentage（参见 Messaging API v2）都可能产生此类行。

请求示例

{
  "type": "TASK_TYPE_EXPORT_MESSAGE_RECIPIENTS",
  "export_message_recipients": {
    "message_id": "22875465358",
    "application": "6D382-5ADFE",
    "type": "holdout",
    "date_from": "2026-08-01T00:00:00Z",
    "date_to": "2026-09-30T00:00:00Z"
  }
}

200：成功

{
  "uid": "29820"
}

与消息历史记录导出一样，轮询 status 并调用 result。result 返回 export_message_recipients_result，而不是 export_messages_v2_result：

{
  "export_message_recipients_result": {
    "file": "Message_22875465358_Holdout_29820-fe5d8ba468df25b7.csv",
    "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Message_22875465358_Holdout_29820-fe5d8ba468df25b7.csv"
  }
}

sends、deliveries 和 opens 共用同一组列：hwid, user_id, platform, send_timestamp, delivery_timestamp, open_timestamp, send_error, pae, send_status。当平台已接受发送但未为其显示任何可见提醒时，pae 为 false，这与汇总统计中 unshowable_sends 统计的情况相同。holdout 有自己更短的一组列：hwid, user_id, platform, holdout_timestamp。