异步消息统计导出

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

何时使用 export 而非 messages:list

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

导出流程如何运作

1. 使用与 messages:list 相同的筛选器调用 export。响应会立即返回一个 uid 任务标识符，此时文件尚未生成。
2. 使用该 uid 轮询 status，直到其报告 STATUS_SUCCESS（或 STATUS_FAILED）。
3. 使用相同的 uid 调用 result 以获取生成的文件名。
4. 按文件名 下载 文件。

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

方法

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

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

export

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

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

标头

请求需要一个 Server API token：

名称	必需	描述
Authorization	是	Server API token。必须以下列格式提供：Authorization: Api <Server Key>。

请求体参数

请求体接受以下字段：

名称	必需	类型	描述
type	是	String	必须是 “TASK_TYPE_EXPORT_MESSAGES_V2”。
export_messages_v2	是	Object	导出参数，如下所述。
export_messages_v2.application_code	见备注	String	Pushwoosh application code。如果未设置 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_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: OK

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

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

{
  "export_messages_v2_result": {
    "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}

在 status 报告 "STATUS_SUCCESS" 之前调用 result 会返回一个空结果。请将 file 的值原样传递给下载端点。

lastTasks

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

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

请求体参数

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

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

注意

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

请求示例

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

200: OK

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

delete

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

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

请求体参数

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

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

请求示例

{
  "uid": "177458"
}

200: OK

{}

下载

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

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

标头

认证方式与其他方法相同，或依赖于一个有效的 Control Panel 会话：

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

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

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

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