비동기 메시지 통계 내보내기

exportMessagesStatistics는 메시지 기록 및 통계를 서버의 CSV 파일로 내보냅니다. messages:list가 처리할 수 없는 대규모 또는 전체 계정 데이터를 가져올 때 사용하세요.

messages:list 대신 내보내기를 사용해야 하는 경우

messages:list는 제한된 기간의 실시간, 페이지네이션된 조회를 위해 사용합니다. 결과가 messages:list의 딥 페이지네이션 한도(page × per_page > 100000)를 초과하거나, 페이지네이션된 JSON 대신 다운로드 가능한 단일 파일을 목표로 할 때 exportMessagesStatistics를 사용하세요. 내보내기는 결과를 하나의 응답에 보관하는 대신 디스크의 파일로 스트리밍하므로 date_range나 행 수에 제한이 없습니다.

내보내기 흐름 작동 방식

messages:list와 동일한 필터로 export를 호출합니다. 응답은 파일이 생성되기 전에 즉시 uid 작업 식별자를 반환합니다.
해당 uid로 status를 폴링하여 STATUS_SUCCESS(또는 STATUS_FAILED)를 보고할 때까지 기다립니다.
동일한 uid로 result를 호출하여 생성된 file과 바로 사용할 수 있는 file_url을 가져옵니다.
파일을 다운로드합니다. file_url을 그대로 사용하거나, 비어 있는 경우 result를 참조하여 file에서 URL을 구성하세요.

lastTasks를 사용하여 애플리케이션의 최근 내보내기 작업을 조회하고, delete를 사용하여 작업을 취소하거나 보존 기간 전에 파일을 제거하세요.

메서드

내보내기 라이프사이클에는 5개의 메서드와 일반 다운로드 엔드포인트가 있습니다:

메서드	설명
`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<wbr/>_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	`messages:list`에서 사용하는 플랫폼 이름 문자열이 아닌 플랫폼 코드 (숫자, 예: iOS의 경우 `1`).
`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"

요청 예시

{
  "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
401: 잘못된 API 액세스 토큰

{
  "uid": "177458"
}

{
  "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 사이의 분수입니다. result를 호출하기 전에 status가 "STATUS_SUCCESS"에 도달할 때까지 폴링하세요.

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",
    "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) 이후에 생성된 작업만 반환합니다.

요청 예시

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

{}

다운로드

result에서 생성된 CSV 파일을 이름으로 다운로드합니다.

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

헤더

다른 메서드와 동일한 방식으로 인증하거나 활성 Control Panel 세션에 의존합니다:

이름	필수	설명
`Authorization`	예	서버 API 토큰, 다른 `exportMessagesStatistics` 메서드와 동일한 형식: `Authorization: Api <Server Key>` (`Api` 스킴은 대소문자를 구분하지 않음). `Authorization` 헤더가 없고 로그인된 Control Panel 세션이 없는 요청은 `401 Unauthorized`를 받습니다.

<file>을 result 응답의 정확한 file 값으로 바꾸세요. 예:

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

파일은 properties에서 선택한 열을 포함하는 CSV입니다. 내보내기가 완료된 후 7일 동안 사용할 수 있으며, 그 후 정리 작업이 파일을 제거하고 URL은 더 이상 확인되지 않습니다.