메시지 통계

이 메서드들은 전송한 메시지에 대한 통계를 반환합니다. 전송된 메시지 목록을 조회하고, 메시지의 시간별 메트릭을 가져오고, 전송 퍼널에서 메시지가 어느 단계에서 잠재고객을 잃었는지 확인하고, 기기별 메시지 로그를 읽고, 이메일의 링크 클릭 수를 집계하는 데 사용합니다.

messages:list

전송된 메시지 목록을 표시합니다.

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

헤더

이름	필수	설명
`Authorization`	예	서버 API 토큰. 다음 형식으로 제공해야 합니다: `Authorization: Api <Server Key>`.

요청 본문 매개변수

이름	필수	유형	설명
`platforms`	아니요	배열	메시지 플랫폼. 가능한 값: `"IOS"`, `"ANDROID"`, `"OSX"`, `"WINDOWS"`, `"AMAZON"`, `"SAFARI"`, `"CHROME"`, `"FIREFOX"`, `"IE"`, `"EMAIL"`, `"HUAWEI_ANDROID"`, `"SMS"`.
`date_range`	아니요	객체	보고 기간, 메시지 생성 날짜로 필터링됩니다. `date_from` 및 `date_to`는 `YYYY-MM-DD` 형식을 따라야 합니다(예: `"2000-01-01"`). 두 날짜 모두 전체가 포함되므로 `date_from`과 `date_to`를 같은 날짜로 설정하면 해당 날짜 전체가 반환됩니다. 날짜는 계정 시간대가 아닌 UTC로 해석됩니다.
`campaign`	아니요	문자열	캠페인 코드
`filters`	예	객체	메시지 필터.
`source`	아니요	문자열	메시지 소스. 예: `AB_TEST`, `API`, `AUTO_PUSH`, `CP`, `CSV`, `CUSTOMER_JOURNEY`, `EMAIL_API`, `EMAIL_CP`, `GEO_ZONE`, `PUSH_ON_EVENT`, `RSS`.
`messages_codes`	아니요	배열	`/createMessage` API 응답에서 얻은 메시지 코드.
`messages_ids`	아니요	배열	메시지 기록에서 얻은 메시지 ID
`message_type`	아니요	문자열	메시지 흐름 필터. 가능한 값: `"TRANSACTIONAL"`, `"BROADCAST"`, `"ALL"`. 생략하면 기본값은 `"ALL"`입니다.
`params`	아니요	객체	메시지 세부 정보와 메트릭을 표시할지 여부를 지정합니다. 응답에 `"details"` 객체를 포함하려면 `with_details: true`로 설정하고, `"metrics"` 객체를 포함하려면 `with_metrics: true`로 설정합니다.
`application`	예	문자열	Pushwoosh 애플리케이션 코드.
`per_page`	아니요	정수	페이지당 결과 수, `1`에서 `499`까지. 매개변수를 생략하면 기본 페이지 크기인 500개의 결과를 얻습니다. `500` 이상을 명시적으로 전달하면 `400`으로 거부됩니다.
`page`	아니요	정수	페이지네이션을 위한 0부터 시작하는 페이지 번호. 아래의 딥 페이지네이션 제한을 참조하세요.

messages:list는 page × per_page가 100,000개 결과를 초과하는 요청을 거부합니다. 제한 내에 머물려면 date_range를 좁히거나 더 작은 per_page를 사용하세요.

total은 필터와 일치하는 메시지의 정확한 수이며, 이 수가 100,000 이하일 때까지입니다. 그 이상이면 100001에서 멈춥니다. 이는 이 엔드포인트가 페이징할 수 있는 양보다 많다는 의미입니다. 해당 제한을 초과하여 페이지 루프를 설정하지 마세요. 제한을 초과하는 페이지는 비어 있는 것이 아니라 거부됩니다. 그보다 많은 메시지를 포함하는 기간을 가져오려면 요청당 date_range를 좁히거나, 전체 기간을 페이징 없이 하나의 CSV 파일에 쓰는 비동기 내보내기를 사용하세요.

message_type은 날짜를 지정하지 않은 요청이 거슬러 올라가는 범위도 제한합니다.

요청 예시

{
    "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",             // 캠페인 코드
      "messages_ids": [],               // 메시지 ID
      "messages_codes": [],             // 메시지 코드
      "message_type": "ALL",            // TRANSACTIONAL, BROADCAST, ALL (기본값)
      "application": "string"           // Pushwoosh 애플리케이션 코드
    },
    "params": {
      "with_details": true,             // 응답에 메시지 세부 정보 추가 ("details" 객체)
      "with_metrics": true              // 응답에 메시지 메트릭 추가 ("metrics" 객체)
    },
    "per_page": 20,                     // <= 499
    "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
      }]
    }
  }]
}

date_range가 30일을 초과합니다:

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

page × per_page가 딥 페이지네이션 제한을 초과합니다:

{
  "error": "requested result window is too large, narrow the date range"
}

{
  "error": "account not found"
}

totalsByIntervals

메시지 코드를 기반으로 시간별로 집계된 메트릭 및 전환 데이터를 반환합니다.

POST https://api.pushwoosh.com/api/v2/statistics/messages/totalsByIntervals

인증

인증은 요청 헤더의 API 액세스 토큰을 통해 처리됩니다.

요청 본문 매개변수

매개변수 이름	유형	설명	필수
`message_code`	string	`/createMessage` API 응답에서 얻은 메시지 코드.	예
`platforms`	[int]	플랫폼	아니요

요청 예시

{
  "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // 필수. 고유 메시지 식별자
  "platforms": [1, 3, 7, 10, 11, 12]          // 선택 사항. 플랫폼 코드 목록
}

응답 필드

이름	유형	설명
`metrics`	배열	메시지 메트릭 배열을 포함합니다
`timestamp`	string	메트릭의 시간입니다.
`platform`	int	플랫폼 코드(예: iOS, Android).
`sends`	string	전송된 메시지 수.
`opens`	string	열람된 메시지 수.
`deliveries`	string	전송 완료된 메시지 수.
`inbox_opens`	string	받은 편지함 열람 수.
`unshowable_sends`	string	OS 설정에서 알림이 꺼진 기기로 수락된 메시지 수입니다. 배너는 표시되지 않지만 메시지는 앱에 도달하며, 전송 시 받은 편지함에 메시지 저장이 활성화된 경우 메시지 받은 편지함에 나타납니다. 오류가 아닌 성공적인 전송으로 계산됩니다.
`errors`	string	오류 수.
`conversion`	객체	전환 데이터를 포함합니다
`sends`	string	총 전송된 메시지 수.
`opens`	string	총 열람된 메시지 수.
`events`	배열	통계가 포함된 이벤트 배열
`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                       // 이벤트로 발생한 수익(금액/통화 속성이 있는 이벤트에만 해당)
    }]
  }
}

전송 퍼널

메시지 또는 캠페인이 어느 단계에서 잠재고객을 잃었는지(오류, 미전송, 미열람) 그리고 그 이유를 확인하려면 전송 퍼널을 사용하세요. 시간별 합계를 반환하는 totalsByIntervals와 달리, 퍼널은 잠재고객을 단계와 이탈 이유별로 세분화하며, 채널당 하나의 항목과 플랫폼별 세분화를 제공합니다. 단계 순서는 채널마다 다릅니다. 각 채널이 어떤 단계를 포함하는지는 아래 GetDeliveryFunnelResponse 필드의 stage를 참조하세요. 두 메서드 모두 서버 API 토큰이 필요합니다.

두 메서드 모두 동일한 응답 형태인 GetDeliveryFunnelResponse를 반환하며, 아래에서 한 번만 설명합니다.

getDeliveryFunnel

한 메시지의 퍼널을 반환합니다.

POST https://api.pushwoosh.com/api/v2/statistics/messages/getDeliveryFunnel

헤더

이름	필수 여부	설명
`Authorization`	예	서버 API 토큰. 다음 형식으로 제공해야 합니다: `Authorization: Api <Server Key>`.

요청 본문 매개변수

이름	필수 여부	유형	설명
`message_code`	예	문자열	`/createMessage` API 응답에서 얻은 메시지 코드.
`platforms`	아니요	정수 배열	퍼널을 필터링할 플랫폼 코드. 메시지가 전송된 모든 플랫폼을 반환하려면 생략하세요.

요청 예시

{
  "message_code": "A444-AAABBBCC-00112233",  // /createMessage의 메시지 코드
  "platforms": [1, 14]                        // 선택 사항. iOS, Email
}

GetDeliveryFunnelResponse 필드

이름	유형	설명
`channels`	배열	메시지가 전송된 각 채널당 하나의 항목.
`window_from`, `window_to`	문자열 또는 null	사용 가능한 데이터를 기준으로 퍼널이 다루는 기간. `funnel_state`가 `FUNNEL_STATE_READY`가 아닐 때 `null`.
`funnel_state`	문자열	`FUNNEL_STATE_READY`: 아래 퍼널이 채워져 있습니다. `FUNNEL_STATE_NO_EVENTS`: 이 메시지에 대해 아직 아무 일도 발생하지 않았습니다. `FUNNEL_STATE_EXPIRED`: 메시지가 너무 오래전에 전송되어 퍼널 데이터가 더 이상 사용할 수 없습니다. 두 non-`READY` 경우 모두 `channels`가 비어 있습니다. 알 수 없거나, 다른 계정에 속하거나, 삭제된 `message_code`는 이러한 상태 중 어느 것도 아닙니다. 아래 `404` 응답을 참조하세요.

channels[]

이름	유형	설명
`channel`	문자열	`CHANNEL_MOBILE_PUSH`(iOS, macOS, Android, Amazon, Huawei), `CHANNEL_WEB_PUSH`(Safari, Chrome, Firefox), `CHANNEL_EMAIL`, `CHANNEL_OTHER`(SMS, 메신저, Wallet, Windows, Baidu, Xiaomi), `CHANNEL_APP_INBOX`.
`funnel`	배열	이 채널의 퍼널 단계, 아래 `funnel[]` 참조.
`deliveries_form`	문자열	`STAGE_DELIVERIES` 단계가 어떤 세분화를 포함하는지: `DELIVERIES_FORM_PER_DEVICE`(기기가 알림을 표시할지 여부와 확인 여부에 따라 분리된 네 개의 배타적 행) 또는 `DELIVERIES_FORM_BASIC`(알림 상태 구분 없이 두 개의 행).
`basic_form_reason`	문자열	`deliveries_form`이 `DELIVERIES_FORM_BASIC`일 때만 의미가 있습니다: `BASIC_FORM_REASON_RETENTION`(메시지가 너무 오래되어 기기별 세분화가 불가능), `BASIC_FORM_REASON_UNAVAILABLE`(이 계정 또는 메시지에 대해 기기별 세분화를 사용할 수 없음, 예: 시스템 메시지), `BASIC_FORM_REASON_NO_DELIVERIES`(아직 아무것도 수락되지 않음), `BASIC_FORM_REASON_NOT_APPLICABLE`(채널에 알림 상태 자체가 없음, 예: email 또는 App Inbox). 그렇지 않으면 `BASIC_FORM_REASON_UNSPECIFIED`: `deliveries_form`이 `DELIVERIES_FORM_BASIC`이 아니라면 이 필드는 무시하세요.
`confirmed_deliveries`	객체	확인된 전송의 `count` 및 `platforms`별 세분화. `STAGE_DELIVERIES`의 개수로 제한되지 않으므로 그와 다를 수 있습니다.

funnel[](단일 단계)

이름	유형	설명
`stage`	문자열	`STAGE_AUDIENCE`(메시지가 타겟팅한 모든 사람), `STAGE_SENT`(푸시 서비스 또는 이메일 제공업체가 수락함), `STAGE_ERRORS`(수락되기 전에 거부됨), `STAGE_DELIVERIES`(수락됨, 확인 여부로 구분), `STAGE_OPENED`(열람한 고유 기기, 또는 App Inbox의 경우 사용자가 탭하여 연 항목), `STAGE_INTERACTIONS`(이메일 전용: 클릭, 구독 취소, 신고), `STAGE_REACHED`/`STAGE_READ`(App Inbox 전용, `STAGE_DELIVERIES`를 대체함).
`count`	문자열	단계의 총계, 숫자 문자열로 표현.
`pieces`	배열	단계 자체의 세분화. `errors`를 대신 사용하는 `STAGE_ERRORS`에서는 비어 있음. 각 항목은 `kind`(`KIND_PASSED`는 다음 단계로 넘어감, `KIND_REASON`은 넘어가지 않음, `KIND_SUBSET`은 나머지 둘과 겹치며 절대 합산되지 않음), `category`(각 단계별 값 목록은 아래 참조), `count`, `platforms`별 세분화를 가집니다.
`errors`	배열	`STAGE_ERRORS` 전용: `category`(값 목록은 아래 참조), `count`, `platforms`, 그리고 `codes`: 이 카테고리로 그룹화된 원시 제공업체 오류 코드(`platform`, `code`, `name`, `count`). 각 `name`의 의미와 해결 방법은 전송 오류를 참조하세요.
`platforms`	배열	단계의 총계, 플랫폼별로 구분됨.

category 값

STAGE_AUDIENCE:

ELIGIBLE_AUDIENCE(통과): 아래 어떤 이유로도 제외되지 않음.
FREQUENCY_CAPPING: 빈도 제한으로 건너뜀.
CONTROL_GROUP: 대조군으로 보류됨.
UNSUBSCRIBED: 수신자가 구독을 취소함.
BOUNCED: 수신자의 주소가 이전에 반송됨.
COMPLAINT: 수신자가 이전에 메시지를 스팸으로 표시함.
FILTERED_BY_CATEGORY: 수신자가 이 메시지 카테고리를 수신 거부함.

STAGE_ERRORS:

NO_TOKEN: 기기에 전송할 푸시 토큰이나 주소가 없음.
NO_DEVICE: 일치하는 기기를 찾을 수 없음.
PLATFORM_DISABLED: 이 앱에서 플랫폼이 비활성화됨.
INVALID_TOKEN: 제공업체가 기기 토큰 또는 주소를 유효하지 않은 것으로 거부함.
QUOTA_EXCEEDED: 제공업체가 전송 속도를 제한함.
INVALID_CONTENT: 작성된 그대로 메시지를 보낼 수 없었음. 대부분 제공업체에 의해 거부된 것이 아니라, 손상된 Connected Content나 Liquid 블록과 같이 템플릿 자체가 빌드에 실패한 경우입니다.
INVALID_CONFIGURATION: 계정 자체의 제공업체 설정이 손상됨, 예: 잘못된 자격 증명, 삭제된 Firebase 프로젝트, 허용되지 않는 APNs topic.
PROVIDER_ERROR: 제공업체가 위 카테고리 외의 오류를 반환함.
INTERNAL_ERROR: Pushwoosh가 전송을 처리하지 못함.
UNCLASSIFIED_ERROR: 위 카테고리 중 어느 것과도 일치하지 않는 이탈. 드물게 발생할 것으로 예상됩니다.

STAGE_DELIVERIES, DELIVERIES_FORM_PER_DEVICE:

DISPLAYABLE_CONFIRMED(통과): 기기가 알림을 표시했고 수신을 확인함.
DISPLAYABLE_NO_CONFIRMATION: 기기가 알림을 표시할 것이지만 아직 수신을 확인하지 않음.
NOT_DISPLAYABLE_CONFIRMED(통과): 무음 푸시가 수신을 확인함.
NOT_DISPLAYABLE_NO_CONFIRMATION: 무음 푸시가 아직 수신을 확인하지 않음.

STAGE_DELIVERIES, DELIVERIES_FORM_BASIC:

CONFIRMED_BY_DEVICE(통과): 기기가 수신을 확인함.
NO_CONFIRMATION: 아직 확인되지 않음.

이메일은 CONFIRMED_BY_DEVICE와 겹치는 하위 집합으로 추가로 다음을 제공합니다:

BOUNCED_HARD(하위 집합): 주소로 영구적으로 전송할 수 없음.
BOUNCED_SOFT(하위 집합): 주소로 일시적으로 전송할 수 없음, 예: 사서함 가득 참.

BOUNCED_HARD는 다음 하위 집합 행으로 더 세분화될 수 있습니다:

BOUNCED_HARD_GENERAL: 영구적으로 전송할 수 없음, 더 구체적인 이유 없음.
BOUNCED_HARD_MAILBOX_FULL: 수신자의 사서함이 가득 참.
BOUNCED_HARD_MAILBOX_INACTIVE: 수신자의 사서함이 더 이상 존재하지 않음.
BOUNCED_HARD_SUPPRESSED: 제공업체가 해당 주소를 차단 목록에 올림.
BOUNCED_HARD_UNDETERMINED: 영구적으로 전송할 수 없음, 이유 미확인.

BOUNCED_SOFT는 다음 하위 집합 행으로 더 세분화될 수 있습니다:

BOUNCED_SOFT_GENERAL: 일시적으로 전송할 수 없음, 더 구체적인 이유 없음.
BOUNCED_SOFT_MAILBOX_FULL: 전송 당시 수신자의 사서함이 가득 참.
BOUNCED_SOFT_CONTENT_REJECTED: 수신자의 메일 서버가 메시지 콘텐츠를 거부함.
BOUNCED_SOFT_SPAM: 수신자의 메일 서버가 메시지를 스팸으로 표시함.
BOUNCED_SOFT_MESSAGE_TOO_LARGE: 메시지가 수신자의 사서함에 비해 너무 큼.
BOUNCED_SOFT_ATTACHMENT_REJECTED: 수신자의 메일 서버가 첨부 파일을 거부함.
BOUNCED_SOFT_CUSTOM_TIMEOUT_EXCEEDED: 수신자의 메일 서버가 응답하는 데 너무 오래 걸림.
BOUNCED_SOFT_UNDETERMINED: 일시적으로 전송할 수 없음, 이유 미확인.
BOUNCED_UNDETERMINED: 수신자의 서버가 이메일을 수락했지만 전달을 확인하지 않음. 결과를 알 수 없으며 주소가 차단되지 않음. 소프트 반송으로 계산됨.

BOUNCED_UNCLASSIFIED는 위의 어떤 하위 유형과도 일치하지 않는 반송(하드 또는 소프트)입니다. 드물게 발생할 것으로 예상되며, 이를 기반으로 로직을 구축할 값이 아닙니다.

STAGE_OPENED, 이메일 전용(다른 채널은 pieces 없이 단계의 count만 보고함):

OPENED_BY_RECIPIENT(통과): 사람이 열람함.
MACHINE_OPENS_ONLY: 자동화된 스캐너만 열람함.
OPEN_TYPE_UNKNOWN: 사람인지 스캐너인지 분류할 수 없음.
MACHINE_OPENS_AMPP(하위 집합): 이 메시지에 대해 사람/스캐너 구분을 사용할 수 없을 때 위 세 행을 대체함. 대신 Apple Mail Privacy Protection 자체의 기계 열람 수를 계산하며, 단계 총계와 겹침.

STAGE_INTERACTIONS, 이메일 전용:

CLICKED_ONLY(통과): 링크를 클릭했고 계속 구독 중.
CLICKED_AND_UNSUBSCRIBED: 링크를 클릭하고 구독을 취소함.
CLICKED_AND_COMPLAINED: 링크를 클릭하고 메시지를 스팸으로 표시함.
UNSUBSCRIBED_WITHOUT_CLICK: 클릭 없이 구독을 취소함.
COMPLAINED_WITHOUT_CLICK: 클릭 없이 메시지를 스팸으로 표시함.

STAGE_REACHED, App Inbox 전용:

REACHED(통과): 앱이 항목을 최소 한 번 가져옴.
NOT_FETCHED_YET: 아직 가져오지 않음.

STAGE_READ, App Inbox 전용:

READ(통과): 읽음으로 표시됨.
DISMISSED_UNREAD: 사용자가 읽지 않고 삭제함.
UNREAD: 여전히 받은편지함에 읽지 않은 상태로 있음.
EXPIRED_UNREAD: UNREAD와 동일하지만 이후 항목이 만료되어 받은편지함에서 사라짐.
DISMISSED(하위 집합): 읽었든 아니든 삭제된 모든 항목. READ 및 DISMISSED_UNREAD와 겹침.

응답 코드

{
  "channels": [{
    "channel": "CHANNEL_MOBILE_PUSH",
    "funnel": [
      { "stage": "STAGE_AUDIENCE", "count": "10000", "pieces": [
        { "kind": "KIND_PASSED", "category": "ELIGIBLE_AUDIENCE", "count": "10000", "platforms": [{ "platform": 1, "count": "10000" }] }
      ], "errors": [], "platforms": [{ "platform": 1, "count": "10000" }] },
      { "stage": "STAGE_SENT", "count": "9820", "pieces": [], "errors": [], "platforms": [{ "platform": 1, "count": "9820" }] },
      { "stage": "STAGE_ERRORS", "count": "180", "pieces": [], "errors": [
        { "category": "INVALID_TOKEN", "count": "180", "platforms": [{ "platform": 1, "count": "180" }], "codes": [
          { "platform": 1, "code": 1002, "name": "BadDeviceToken", "count": "180" }
        ] }
      ], "platforms": [{ "platform": 1, "count": "180" }] },
      { "stage": "STAGE_DELIVERIES", "count": "9820", "pieces": [
        { "kind": "KIND_PASSED", "category": "DISPLAYABLE_CONFIRMED", "count": "8000", "platforms": [{ "platform": 1, "count": "8000" }] },
        { "kind": "KIND_REASON", "category": "DISPLAYABLE_NO_CONFIRMATION", "count": "820", "platforms": [{ "platform": 1, "count": "820" }] },
        { "kind": "KIND_PASSED", "category": "NOT_DISPLAYABLE_CONFIRMED", "count": "900", "platforms": [{ "platform": 1, "count": "900" }] },
        { "kind": "KIND_REASON", "category": "NOT_DISPLAYABLE_NO_CONFIRMATION", "count": "100", "platforms": [{ "platform": 1, "count": "100" }] }
      ], "errors": [], "platforms": [{ "platform": 1, "count": "9820" }] },
      { "stage": "STAGE_OPENED", "count": "3120", "pieces": [], "errors": [], "platforms": [{ "platform": 1, "count": "3120" }] }
    ],
    "deliveries_form": "DELIVERIES_FORM_PER_DEVICE",
    "basic_form_reason": "BASIC_FORM_REASON_UNSPECIFIED",
    "confirmed_deliveries": { "count": "8900", "platforms": [{ "platform": 1, "count": "8900" }] }
  }],
  "window_from": "2026-09-01T00:00:00Z",
  "window_to": "2026-09-01T00:05:00Z",
  "funnel_state": "FUNNEL_STATE_READY"
}

빈 channels 배열과 funnel_state: "FUNNEL_STATE_NO_EVENTS"는 이 메시지에 대해 아직 아무 일도 발생하지 않았음을 의미합니다. 이는 오류가 아닙니다. 퍼널 데이터를 사용할 수 없을 만큼 너무 오래전에 전송된 message_code도 빈 channels 배열과 funnel_state: "FUNNEL_STATE_EXPIRED"와 함께 200을 반환합니다.

알 수 없거나, 다른 계정에 속하거나, 이후 삭제된 message_code:

{
  "error": "message not found"
}

{
  "error": "invalid auth token"
}

getCampaignDeliveryFunnel

캠페인의 메시지들에 대해 getDeliveryFunnel을 합산합니다. 고유 수는 메시지별로 계산됩니다: 캠페인의 여러 메시지에 도달한 구독자는 각 메시지마다 한 번씩 계산됩니다.

POST https://api.pushwoosh.com/api/v2/statistics/messages/getCampaignDeliveryFunnel

헤더

이름	필수 여부	설명
`Authorization`	예	서버 API 토큰. 다음 형식으로 제공해야 합니다: `Authorization: Api <Server Key>`.

요청 본문 매개변수

이름	필수 여부	유형	설명
`campaign_code`	예	문자열	캠페인 코드.
`platforms`	아니요	정수 배열	퍼널을 필터링할 플랫폼 코드. 캠페인이 전송된 모든 플랫폼을 반환하려면 생략하세요.

요청 예시

{
  "campaign_code": "AAAAA-XXXXX",  // 캠페인 코드
  "platforms": [1, 14]             // 선택 사항. iOS, Email
}

응답

위의 GetDeliveryFunnelResponse와 동일한 형태입니다.

응답 코드

지정된 campaign_code와 platforms에 대한 빈 잠재고객도 빈 channels 배열과 funnel_state: "FUNNEL_STATE_NO_EVENTS"와 함께 200을 반환합니다. 퍼널 데이터를 사용할 수 없을 만큼 너무 오래전에 전송된 캠페인도 빈 channels 배열과 funnel_state: "FUNNEL_STATE_EXPIRED"와 함께 200을 반환합니다. 둘 다 오류가 아닙니다.

알 수 없거나, 다른 계정에 속하거나, 메시지가 모두 삭제된 campaign_code. 일부 메시지만 삭제된 캠페인은 영향을 받지 않습니다. 삭제된 메시지도 여전히 퍼널에 계산됩니다.

{
  "error": "campaign not found"
}

{
  "error": "invalid auth token"
}

getMessageLog

전송된 메시지에 대한 자세한 정보를 표시합니다.

POST https://api.pushwoosh.com/api/v2/statistics/getMessageLog

헤더

이름	필수	설명
`Authorization`	필수	Pushwoosh 제어판의 API 액세스 토큰.

요청 본문 매개변수

이름	필수	유형	설명
`message_id`	아니요	정수	메시지 기록에서 얻은 메시지 ID로 메시지 이벤트를 선택합니다. 예: `12345678900`.
`message_code`	아니요	문자열	`/createMessage` API 응답에서 얻은 메시지 코드로 메시지 이벤트를 선택합니다. 예: `"A444-AAABBBCC-00112233"`.
`campaign_code`	아니요	문자열	메시지 페이로드에 지정된 캠페인 코드로 메시지 이벤트를 선택합니다. 예: `"AAAAA-XXXXX"`.
`hwid`	아니요	문자열 또는 배열	HWID (하드웨어 ID) 또는 HWID 배열로 메시지 이벤트를 선택합니다.
`date_from`	`message_id`, `message_code` 또는 `campaign_code`가 제공되지 않은 경우 필수	날짜/시간	메시지 필터링 시작 날짜. 형식: `"YYYY-MM-DD HH:MM:SS"`. 예: `"2000-01-25 00:00:00"`.
`date_to`	`message_id`, `message_code` 또는 `campaign_code`가 제공되지 않은 경우 필수	날짜/시간	메시지 필터링 종료 날짜. 형식: `"YYYY-MM-DD HH:MM:SS"`. 예: `"2000-01-26 00:00:00"`.
`limit`	아니요	정수	단일 응답으로 반환되는 최대 메시지 이벤트 수. 최대값: `100000`.
`pagination_token`	아니요	문자열	이전 `/getMessageLog` 응답에서 얻은 페이지네이션 토큰. 추가 결과를 검색하는 데 사용합니다.
`user_id`	아니요	문자열	사용자 지정 사용자 ID로 메시지 이벤트를 선택합니다. 자세한 내용은 `/registerUser`를 참조하세요.
`application_code`	예	문자열	Pushwoosh 애플리케이션 코드로 메시지 이벤트를 선택합니다.
`actions`	아니요	배열	특정 메시지 작업으로 결과를 필터링합니다. 가능한 값: `"sent"`, `"delivered"`, `"opened"`, `"reject"`, `"create"`, `"inbox_delivered"`, `"inbox_read"`, `"inbox_opened"`, `"inbox_deleted"`. `"create"` 이벤트는 기본적으로 응답에서 제외됩니다. 이를 보려면 이 배열에 `"create"`를 포함하세요. `"delivered"` 이벤트는 추가로 계정에서 전송 통계를 활성화해야 합니다.
`platforms`	아니요	배열	결과를 필터링할 대상 플랫폼 배열. 가능한 값: `"unknown"`, `"ios"`, `"blackberry"`, `"android"`, `"windows phone"`, `"osx"`, `"windows"`, `"amazon"`, `"safari"`, `"chrome"`, `"firefox"`, `"ie"`, `"email"`, `"fb messenger"`, `"baidu android"`, `"huawei android"`, `"sms"`, `"xiaomi"`, `"web"`, `"whatsapp"`, `"line"`, `"kakao"`, `"telegram"`, `"apple wallet"`, `"google wallet"`, `"viber"`.
`message_type`	아니요	문자열	메시지 흐름으로 결과를 필터링합니다. `"all"`(생략 시 기본값)은 모든 것을 반환하고, `"broadcast"`는 대량 메시지(`message_id != 0`)만 반환하며, `"transactional"`은 Customer Journey에서 보낸 메시지를 포함하여 `message_id = 0`인 메시지만 반환합니다.

요청 예시

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 앱 코드
   "message_code": "A444-AAABBBCC-00112233",       // 선택 사항, /createMessage 요청에서 얻은 메시지 코드
   "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", "delivered", "opened", "reject", "create", "inbox_delivered", "inbox_read", "inbox_opened", "inbox_deleted". 응답에는 지정된 작업이 있는 모든 메시지가 포함됩니다.
   "platforms": ["ios", "chrome"],                 // 선택 사항, 결과 필터링에 사용되며 소문자만 가능합니다. 가능한 값: "unknown", "ios", "blackberry", "android", "windows phone", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "fb messenger", "baidu android", "huawei android", "sms", "xiaomi", "web", "whatsapp", "line", "kakao", "telegram", "apple wallet", "google wallet", "viber"
   "message_type": "broadcast"                     // 선택 사항, "all"(기본값), "broadcast"(message_id != 0) 또는 "transactional"(message_id = 0, Customer Journey 전송 포함)
}'

응답 코드 및 예시

{
  "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"
  }, {
    "timestamp": "2000-01-25T11:19:30Z",
    "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": "reject",
    "status": "failed",
    "error_reason": "invalid device token",
    "payload": "SOME_PAYLOAD_STRING"
  }]
}

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

{
  "error": "account not found"
}

data의 각 항목에는 error_reason(문자열, status가 "failed"일 때 실패 이유로 채워짐)과 선택적 payload(문자열)도 포함됩니다.

응답 페이지는 요청된 limit보다 짧게 반환될 수 있습니다. 그것만으로는 내보내기가 완료되었다는 의미가 아닙니다.

이메일 통계

linksInteractions

이메일의 링크 클릭에 대한 통계를 표시합니다

POST https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractions

헤더

이름	필수	설명
`Authorization`	예	Pushwoosh 제어판의 API 액세스 토큰.

요청 본문 매개변수

이름	필수	유형	설명
`date_range`	아니요	객체	보고 기간을 정의합니다. `date_from`과 `date_to`를 포함합니다.
`filters`	예	객체	이메일 필터.
`application`	예	문자열	Pushwoosh 애플리케이션 코드 (또는 `campaign`, `messages_ids`, `message_codes`를 지정).
`messages_codes`	예	배열	메시지 코드 (또는 `application`, `campaign`, `messages_ids`를 지정).
`campaign`	예	문자열	캠페인 코드 (또는 `application`, `messages_ids`, `message_codes`를 지정).
`messages_ids`	예	배열	메시지 ID (또는 `application`, `campaign`, `message_codes`를 지정).
`link_template`	`application` 또는 `campaign`이 지정된 경우 필수.	문자열	키워드로 이메일 링크 상호 작용을 필터링합니다. URL에 지정된 텍스트를 포함하는 링크만 API 응답으로 반환됩니다. 예를 들어, 이메일에 `https://example.com/news`와 `https://example.com/shop` 같은 링크가 포함된 경우, `"link_template": "shop"`으로 설정하면 `https://example.com/shop`에 대한 상호 작용만 반환됩니다.
`email_content_code`	아니요	문자열	이메일 콘텐츠의 고유 식별자.
`params`	아니요	객체	추가 응답 옵션을 정의합니다. 통계가 포함된 전체 링크 목록을 추가하는 `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",               // 캠페인 코드 (대신 application, messages_ids 또는 message_codes를 지정할 수 있습니다)
      "application": "string",            // 애플리케이션 코드 (대신 campaign, messages_ids 또는 message_codes를 지정할 수 있습니다)
      "messages_ids": [],                 // 메시지 ID (대신 application, campaign 또는 message_codes를 지정할 수 있습니다)
      "messages_codes": [],               // 메시지 코드 (대신 application, campaign 또는 message_ids를 지정할 수 있습니다)
      "link_template": "string",          // 링크 템플릿 (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

헤더

이름	필수	설명
`Authorization`	예	Pushwoosh 제어판의 API 액세스 토큰.

요청 본문 매개변수

이름	필수	유형	설명
`date_range`	아니요	객체	보고 기간을 정의합니다. `date_from`과 `date_to`를 포함합니다.
`filters`	예	객체	이메일 필터.
`application`	예	문자열	Pushwoosh 애플리케이션 코드 (또는 `campaign`, `messages_ids`, `message_codes`를 지정).
`messages_codes`	예	배열	메시지 코드 (또는 `application`, `campaign`, `messages_ids`를 지정).
`campaign`	예	문자열	캠페인 코드 (또는 `application`, `messages_ids`, `message_codes`를 지정).
`messages_ids`	예	배열	메시지 ID (또는 `application`, `campaign`, `message_codes`를 지정).
`link_template`	`application` 또는 `campaign`이 지정된 경우 필수.	문자열	키워드로 이메일 링크 상호 작용을 필터링합니다. URL에 지정된 텍스트를 포함하는 링크만 API 응답으로 반환됩니다. 예를 들어, 이메일에 `https://example.com/news`와 `https://example.com/shop` 같은 링크가 포함된 경우, `"link_template": "shop"`으로 설정하면 `https://example.com/shop`에 대한 상호 작용만 반환됩니다.
`email_content_code`	아니요	문자열	이메일 콘텐츠의 고유 식별자.
`page`	아니요	정수	페이지네이션을 위한 페이지 번호.
`per_page`	아니요	정수	페이지당 결과 수 (≤ 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",             // 캠페인 코드 (대신 application, messages_ids 또는 message_codes를 지정할 수 있습니다)
      "application": "string",          // 애플리케이션 코드 (대신 campaign, messages_ids 또는 message_codes를 지정할 수 있습니다)
      "messages_ids": [],               // 메시지 ID (대신 application, campaign 또는 message_codes를 지정할 수 있습니다)
      "messages_codes": [],             // 메시지 코드 (대신 application, campaign 또는 message_ids를 지정할 수 있습니다)
      "link_template": "string",        // 링크 템플릿 (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 액세스 토큰을 통해 처리됩니다.

요청 본문 매개변수

매개변수 이름	유형	설명	필수
`application`	string	Pushwoosh 애플리케이션 코드	예
`message_code`	string	메시지 코드.	`date range` 또는 `campaign`이 제공되지 않은 경우 필수
`campaign`	string	캠페인 코드.	`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	페이지 번호, 0부터 시작.	예
`type`	string	반송 유형: Complaint, Softbounce, Hardbounce.	아니요

요청 예시

{
  "application": "XXXXX-XXXXX",               // 필수. Pushwoosh 앱 코드
  "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // campaign 또는 date range가 제공되지 않은 경우 필수.
                                              //          고유 메시지 식별자
  "campaign": "XXXXX-XXXXX",                  // message_code 또는 date range가 제공되지 않은 경우 필수.
                                              //          캠페인 코드
  "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,                                  // 선택 사항. 페이지 번호, 0부터 시작
  "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
  }]
}