메시지 통계

messages:list

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

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

Headers

이름	필수 여부	설명
`Authorization`	예	Server API token. 다음 형식으로 제공되어야 합니다: `Authorization: Api <Server Key>`.

Request body parameters

이름	필수 여부	유형	설명
`platforms`	아니요	Array	메시지 플랫폼. 가능한 값: `"IOS"`, `"ANDROID"`, `"OSX"`, `"WINDOWS"`, `"AMAZON"`, `"SAFARI"`, `"CHROME"`, `"FIREFOX"`, `"IE"`, `"EMAIL"`, `"HUAWEI_ANDROID"`, `"SMS"`.
`date_range`	아니요	Object	보고 기간. `date_from` 및 `date_to`는 `YYYY-MM-DD` 형식을 따라야 합니다(예: `"2000-01-01"`).
`campaign`	아니요	String	캠페인 코드
`filters`	예	Object	메시지 필터.
`source`	아니요	String	메시지 소스. 예: `AB_TEST`, `API`, `AUTO_PUSH`, `CP`, `CSV`, `CUSTOMER_JOURNEY`, `EMAIL_API`, `EMAIL_CP`, `GEO_ZONE`, `PUSH_ON_EVENT`, `RSS`.
`messages_codes`	아니요	Array	`/createMessage` API 응답에서 얻은 메시지 코드.
`messages_ids`	아니요	Array	메시지 기록(Message History)에서 얻은 메시지 ID.
`params`	아니요	Object	메시지 세부 정보 및 지표 표시 여부를 지정합니다. 응답에 `"details"` 객체를 포함하려면 `with_details: true`로, `"metrics"` 객체를 포함하려면 `with_metrics: true`로 설정합니다.
`application`	예	String	Pushwoosh 애플리케이션 코드.
`per_page`	아니요	Integer	페이지당 결과 수 (≤ 1000).
`page`	아니요	Integer	페이지 번호.

Example request

{
    "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": [],             // 메시지 코드
      "application": "string"           // Pushwoosh 애플리케이션 코드
    },
    "params": {
      "with_details": true,             // 응답에 메시지 세부 정보 추가 ("details" 객체)
      "with_metrics": true              // 응답에 메시지 지표 추가 ("metrics" 객체)
    },
    "per_page": 20,                     // <= 1000
    "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
      }]
    }
  }]
}

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

{
  "error": "account not found"
}

totalsByIntervals

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

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

Authorization

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

Request body parameters

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

Request example

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

Response fields

이름	유형	설명
`metrics`	array	메시지 지표 배열을 포함합니다
`timestamp`	string	지표의 시간입니다.
`platform`	int	플랫폼 코드 (예: iOS, Android).
`sends`	string	전송된 메시지 수.
`opens`	string	오픈된 메시지 수.
`deliveries`	string	전송 완료된 메시지 수.
`inbox_opens`	string	인박스 오픈 수.
`unshowable_sends`	string	표시할 수 없는 전송된 메시지 수.
`errors`	string	오류 수.
`conversion`	object	전환 데이터를 포함합니다
`sends`	string	총 전송된 메시지 수.
`opens`	string	총 오픈된 메시지 수.
`events`	array	통계가 포함된 이벤트 배열
`name`	string	이벤트 이름 (예: cart add).
`hits`	string	히트 수.
`conversion`	float	오픈 대비 전환율.
`revenue`	float	수익 (`__amount` 및 `__currency` 속성이 있는 이벤트에만 해당).

Response example

{
  "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                       // 이벤트로 발생한 수익 (amount/currency 속성이 있는 이벤트만 해당)
    }]
  }
}

getMessageLog

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

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

Headers

이름	필수 여부	설명
`Authorization`	필수	Pushwoosh 컨트롤 패널의 API 액세스 토큰.

Request body parameters

이름	필수 여부	유형	설명
`message_id`	아니요	Integer	메시지 기록에서 얻은 메시지 ID로 메시지 이벤트를 선택합니다. 예: `12345678900`.
`message_code`	아니요	String	`/createMessage` API 응답에서 얻은 메시지 코드로 메시지 이벤트를 선택합니다. 예: `"A444-AAABBBCC-00112233"`.
`campaign_code`	아니요	String	메시지 페이로드에 지정된 캠페인 코드로 메시지 이벤트를 선택합니다. 예: `"AAAAA-XXXXX"`.
`hwid`	아니요	String or Array	HWID (하드웨어 ID) 또는 HWID 배열로 메시지 이벤트를 선택합니다.
`date_from`	`message_id`, `message_code`, 또는 `campaign_code`가 제공되지 않은 경우 필수	Datetime	메시지 필터링 시작 날짜입니다. 형식: `"YYYY-MM-DD HH:MM:SS"`. 예: `"2000-01-25 00:00:00"`.
`date_to`	`message_id`, `message_code`, 또는 `campaign_code`가 제공되지 않은 경우 필수	Datetime	메시지 필터링 종료 날짜입니다. 형식: `"YYYY-MM-DD HH:MM:SS"`. 예: `"2000-01-26 00:00:00"`.
`limit`	아니요	Integer	단일 응답에서 반환되는 최대 메시지 이벤트 수입니다. 최대값: `100000`.
`pagination_token`	아니요	String	이전 `/getMessageLog` 응답에서 얻은 페이지네이션 토큰입니다. 추가 결과를 검색하는 데 사용하십시오.
`user_id`	아니요	String	사용자 지정 User ID로 메시지 이벤트를 선택합니다. 자세한 내용은 `/registerUser`를 참조하십시오.
`application_code`	예	String	Pushwoosh 애플리케이션 코드로 메시지 이벤트를 선택합니다.
`actions`	아니요	Array	특정 메시지 작업으로 결과를 필터링합니다. 가능한 값: `"sent"`, `"delivered"`, `"opened"`, `"inbox_delivered"`, `"inbox_read"`, `"inbox_opened"`, `"inbox_deleted"`.
`platforms`	아니요	Array	결과를 필터링할 대상 플랫폼 배열입니다. 가능한 값: `"ios"`, `"android"`, `"osx"`, `"windows"`, `"amazon"`, `"safari"`, `"chrome"`, `"firefox"`, `"ie"`, `"email"`, `"huawei_android"`.

Example request

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",       // 선택 사항, /createMessaage 요청에서 얻은 메시지 코드
   "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", "opened", "delivered", "inbox_delivered", "inbox_read", "inbox_opened", "inbox_deleted". 응답에는 지정된 작업이 포함된 모든 메시지가 포함됩니다.
   "platforms": ["ios", "chrome"]                  // 선택 사항, 결과 필터링에 사용됨. 가능한 값: "ios", "android", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "huawei android"
}'

응답 코드 및 예시

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

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

{
  "error": "account not found"
}

이메일 통계

linksInteractions

이메일 내 링크 클릭 통계를 표시합니다.

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

Headers

이름	필수 여부	설명
`Authorization`	예	Pushwoosh 컨트롤 패널의 API 액세스 토큰.

Request body parameters

이름	필수 여부	유형	설명
`date_range`	아니요	Object	보고 기간을 정의합니다. `date_from` 및 `date_to`를 포함합니다.
`filters`	예	Object	이메일 필터.
`application`	예	String	Pushwoosh 애플리케이션 코드 (또는 `campaign`, `messages_ids`, `message_codes`를 지정할 수 있음).
`messages_codes`	예	Array	메시지 코드 (또는 `application`, `campaign`, `messages_ids`를 지정할 수 있음).
`campaign`	예	String	캠페인 코드 (또는 `application`, `messages_ids`, `message_codes`를 지정할 수 있음).
`messages_ids`	예	Array	메시지 ID (또는 `application`, `campaign`, `message_codes`를 지정할 수 있음).
`link_template`	`application` 또는 `campaign`이 지정된 경우 필수	String	키워드로 이메일 링크 상호 작용을 필터링합니다. URL에 지정된 텍스트가 포함된 링크만 API 응답에 반환됩니다. 예를 들어, 이메일에 `https://example.com/news` 및 `https://example.com/shop`과 같은 링크가 포함되어 있는 경우, “link_template”: “shop”으로 설정하면 `https://example.com/shop`에 대한 상호 작용만 반환됩니다.
`email_content_code`	아니요	String	이메일 콘텐츠에 대한 고유 식별자.
`params`	아니요	Object	추가 응답 옵션을 정의합니다. `with_full_links`를 포함하며, 이는 통계가 포함된 전체 링크 목록을 추가합니다.

Request example

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 배열에 전달됩니다.
   }
}'

Response codes and examples

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

Headers

이름	필수 여부	설명
`Authorization`	예	Pushwoosh 컨트롤 패널의 API 액세스 토큰.

Request body parameters

이름	필수 여부	유형	설명
`date_range`	아니요	Object	보고 기간을 정의합니다. `date_from` 및 `date_to`를 포함합니다.
`filters`	예	Object	이메일 필터.
`application`	예	String	Pushwoosh 애플리케이션 코드 (또는 `campaign`, `messages_ids`, `message_codes`를 지정할 수 있음).
`messages_codes`	예	Array	메시지 코드 (또는 `application`, `campaign`, `messages_ids`를 지정할 수 있음).
`campaign`	예	String	캠페인 코드 (또는 `application`, `messages_ids`, `message_codes`를 지정할 수 있음).
`messages_ids`	예	Array	메시지 ID (또는 `application`, `campaign`, `message_codes`를 지정할 수 있음).
`link_template`	`application` 또는 `campaign`이 지정된 경우 필수	String	키워드로 이메일 링크 상호 작용을 필터링합니다. URL에 지정된 텍스트가 포함된 링크만 API 응답에 반환됩니다. 예를 들어, 이메일에 `https://example.com/news` 및 `https://example.com/shop`과 같은 링크가 포함되어 있는 경우, “link_template”: “shop”으로 설정하면 `https://example.com/shop`에 대한 상호 작용만 반환됩니다.
`email_content_code`	아니요	String	이메일 콘텐츠에 대한 고유 식별자.
`page`	아니요	Integer	페이지 번호.
`per_page`	아니요	Integer	페이지당 결과 수 (≤ 1000).

Request example

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
}'

Response codes and examples

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

날짜, 이메일 주소, 각 반송 사유를 포함하여 이메일 불만 접수(complaints), 소프트 바운스(soft bounces), 하드 바운스(hard bounces)에 대한 데이터를 제공합니다.

Authorization

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

Request body parameters

매개변수 이름	유형	설명	필수 여부
`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(하드 바운스).	아니요

Request example

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

Response fields

필드 이름	유형	설명
`total`	int	총 행 수.
`bounced_emails`	array	반송된 이메일 세부 정보 배열.
├── `email`	string	반송된 이메일 주소.
├── `date`	string	반송 날짜 (형식: `YYYY-MM-DDTHH:MM:SS.000Z`).
├── `reason`	string	반송 사유.
└── `type`	string	반송 유형: Complaint, Softbounce, Hardbounce.

Response example

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