异步消息统计导出

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_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 将不再可用。