이메일 API

createEmailMessage

이메일 메시지를 생성합니다.

POST https://api.pushwoosh.com/json/1.3/createEmailMessage

요청 본문 파라미터

이름	타입	필수	설명
auth	`string`	예	Pushwoosh Control Panel의 API 액세스 토큰입니다.
application	`string`	예	Pushwoosh 애플리케이션 코드
notifications	`array`	예	이메일 메시지 세부 정보를 포함하는 JSON 배열입니다. 아래 알림 파라미터 표를 참조하세요.

알림 파라미터

이름	타입	필수	설명
send_date	`string`	예	이메일을 보낼 시점을 정의합니다. 형식: `YYYY-MM-DD HH:mm` 또는 `"now"`.
preset	`string`	예	이메일 프리셋 코드. Pushwoosh Control Panel의 이메일 콘텐츠 편집기 URL 바에서 복사합니다.
subject	`string` 또는 `object`	아니요	이메일의 제목 줄입니다. 이메일은 항상 콘텐츠의 언어로 전송됩니다. `subject`에 `content`와 일치하는 언어가 포함되어 있지 않으면 제목은 비어 있게 됩니다.
content	`string` 또는 `object`	아니요	이메일 본문 콘텐츠입니다. 일반 HTML 콘텐츠의 경우 문자열이거나, 현지화된 버전의 경우 객체일 수 있습니다.
attachments	`array`	아니요	이메일 첨부 파일입니다. 첨부 파일은 두 개만 사용할 수 있습니다. 각 첨부 파일은 1MB(base64 인코딩)를 초과할 수 없습니다.
list_unsubscribe	`string`	아니요	”Link-Unsubscribe” 헤더에 대한 사용자 지정 URL을 설정할 수 있습니다.
campaign	`string`	아니요	이메일을 특정 캠페인과 연결하기 위한 캠페인 코드입니다.
ignore_user_timezone	`boolean`	아니요	`true`인 경우, 사용자 시간대를 무시하고 즉시 이메일을 보냅니다.
timezone	`string`	아니요	사용자의 시간대에 따라 이메일을 보냅니다. 예: `"America/New_York"`.
filter	`string`	아니요	특정 필터 조건과 일치하는 사용자에게 이메일을 보냅니다.
devices	`array`	아니요	타겟 이메일을 보낼 이메일 주소 목록(최대 1000개)입니다. 사용될 경우, 메시지는 이 주소들로만 전송됩니다. 애플리케이션 그룹이 사용될 경우 무시됩니다.
use_auto_registration	`boolean`	아니요	`true`인 경우, `devices` 파라미터의 이메일을 자동으로 등록합니다.
users	`array`	아니요	설정된 경우, 이메일 메시지는 지정된 사용자 ID (/registerEmail 호출을 통해 등록됨)에게만 전달됩니다. 배열에 1000개 이하의 사용자 ID를 포함할 수 있습니다. “devices” 파라미터가 지정된 경우, “users” 파라미터는 무시됩니다.
dynamic_content_placeholders	`object`	아니요	기기 태그 값 대신 동적 콘텐츠를 위한 플레이스홀더입니다.
conditions	`array`	아니요	태그를 사용한 세분화 조건입니다. 예: `[["Country", "EQ", "BR"]]`.
from	`object`	아니요	애플리케이션 속성의 기본값을 재정의하여 사용자 지정 발신자 이름과 이메일을 지정합니다.
reply-to	`object`	아니요	애플리케이션 속성의 기본값을 재정의하여 사용자 지정 회신 이메일을 지정합니다.
bcc	`array`	아니요	BCC (숨은 참조): 다른 수신자에게 보이지 않게 이메일 사본을 받는 이메일 주소 배열입니다.
email_type	`string`	아니요	이메일 유형을 지정합니다: `"marketing"` 또는 `"transactional"`. 생략될 경우, `PW_ControlGroup: true`인 사용자는 메시지를 받지 않습니다.
email_category	`string`	`email_type`이 `"marketing"`일 때 필수입니다.	구독 환경 설정 센터에 구성된 카테고리 이름 중 하나를 지정합니다(예: 뉴스레터, 프로모션, 제품 업데이트).
transactionId	`string`	아니요	네트워크 문제 발생 시 재전송을 방지하기 위한 고유 메시지 식별자입니다. Pushwoosh 측에서 5분간 저장됩니다.
capping_days	`integer`	아니요	기기당 빈도 제한을 적용할 일수(최대 30일)입니다. 참고: Control Panel에서 전역 빈도 제한이 구성되었는지 확인하세요.
capping_count	`integer`	아니요	`capping_days` 기간 내에 특정 앱에서 특정 기기로 보낼 수 있는 최대 이메일 수입니다. 생성된 메시지가 기기의 `capping_count` 한도를 초과하는 경우, 해당 기기로는 전송되지 않습니다.
capping_exclude	`boolean`	아니요	`true`로 설정하면, 이 이메일은 향후 이메일에 대한 빈도 제한에 포함되지 않습니다.
capping_avoid	`boolean`	아니요	`true`로 설정하면, 이 특정 이메일에는 빈도 제한이 적용되지 않습니다.
send_rate	`integer`	아니요	모든 사용자에 걸쳐 초당 보낼 수 있는 메시지 수를 제한합니다. 대량 발송 시 백엔드 과부하를 방지하는 데 도움이 됩니다.
send_rate_avoid	`boolean`	아니요	true로 설정하면, 이 특정 이메일에는 스로틀링 제한이 적용되지 않습니다.

요청 예시

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // required. API access token from Pushwoosh Control Panel
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code.
    "notifications": [{
      "send_date": "now",               // required. YYYY-MM-DD HH:mm  OR 'now'
      "preset": "ERXXX-32XXX",          // required. Copy Email preset code from the URL bar of
                                        //           the Email Content editor page in Pushwoosh Control Panel.
      "subject": {                      // optional. Email message subject line.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // optional. Email body content.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // optional. Email attachments
        "name": "image.png",            //           "name" - file name
        "content": "iVBANA...AFTkuQmwC" //           "content" - base64 encoded content of the file
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // optional. Allow to set custom URL for "Link-Unsubscribe" header
      "campaign": "CAMPAIGN_CODE",      // optional. To assign this email message to a particular campaign,
                                        //           add a campaign code here.
      "ignore_user_timezone": true,     // optional.
      "timezone": "America/New_York",   // optional. Specify to send the message according to
                                        //           timezone set on user's device.
      "filter": "FILTER_NAME",          // optional. Send the message to specific users meeting filter conditions.
      "devices": [                      // optional. Specify email addresses to send targeted email messages.
        "email_address1",               //           Not more than 1000 addresses in an array.
        "email_address2"                //           If set, the message will only be sent to the addresses on
      ],                                //           the list. Ignored if the Application Group is used.
      "use_auto_registration": true,    // optional. Automatically register emails specified in "devices" parameter
      "users": [                        // optional. If set, the email message will only be delivered to the
        "userId1",                      //           specified user IDs (registered via /registerEmail call).
        "userId2"                       //           Not more than 1000 user IDs in an array.
      ],                                //           If the "devices" parameter is specified,
                                        //           the "users" parameter will be ignored.
      "dynamic_content_placeholders": { // optional. Placeholders for dynamic content instead of device tag values.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // optional. Segmentation conditions, see remark below.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // optional. Specify a sender name and sender email address
        "name": "alias from",           //           to replace the default "From name" and "From email"
        "email": "from-email@email.com" //           set up in application properties.
      },
      "reply-to": {                     // optional. Specify an email address to replace the
        "name": "alias reply to ",      //           default "Reply to" set up in application properties.
        "email": "reply-to@email.com"
      },
      "bcc": [                          // optional. BCC: array of email addresses that receive a copy without other recipients seeing them.
        "bcc1@example.com",
        "bcc2@example.com"
      ],
      "email_type": "marketing",        // optional. "marketing" or "transactional".
                                        // If omitted, users with PW_ControlGroup: true will not receive the message.
      "email_category": "category name",// required when email_type is "marketing". Category name.
      "transactionId": "unique UUID",   // optional. Unique message identifier to prevent re-sending
                                        //           in case of network problems. Stored on the side
                                        //           of Pushwoosh for 5 minutes.
      // Frequency capping params. Ensure that Global frequency capping is configured in the Control Panel.
      // Frequency capping does not apply to transactional messages.
      // In all other cases, including omitted "email_type", frequency capping applies.
      "capping_days": 30,               // optional. Amount of days for frequency capping (max 30 days)
      "capping_count": 10,              // optional. The max number of emails that can be sent from a
                                        //           specific app to a particular device within a 'capping_days'
                                        //           period. In case the message created exceeds the
                                        //           'capping_count' limit for a device, it won't
                                        //           be sent to that device.
      "capping_exclude": true,          // optional. If set to true, this email will not
                                        //           be counted towards the capping for future emails.
      "capping_avoid": true,            // optional. If set to true, capping will not be applied to
                                        //           this specific email.
      "send_rate": 100,                 // optional. Throttling limit.
                                        //           Limit how many messages can be sent per second across all users.
                                        //           Helps prevent backend overload during high-volume sends.
      "send_rate_avoid": true,          // optional. If set to true, throttling limit will not be applied to
                                        //           this specific email.
    }]
  }
}

응답 예시

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}

태그 조건

각 태그 조건은 [tagName, operator, operand]와 같은 배열입니다. 여기서

tagName: 태그의 이름
operator: “EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN”
operand: string | integer | array | date

피연산자 설명

EQ: 태그 값이 피연산자와 같습니다.
IN: 태그 값이 피연산자와 교차합니다 (피연산자는 항상 배열이어야 합니다).
NOTEQ: 태그 값이 피연산자와 같지 않습니다.
NOTIN: 태그 값이 피연산자와 교차하지 않습니다 (피연산자는 항상 배열이어야 합니다).
GTE: 태그 값이 피연산자보다 크거나 같습니다.
LTE: 태그 값이 피연산자보다 작거나 같습니다.
BETWEEN: 태그 값이 최소 피연산자 값보다 크거나 같고 최대 피연산자 값보다 작거나 같습니다 (피연산자는 항상 배열이어야 합니다).

문자열 태그

유효한 연산자: EQ, IN, NOTEQ, NOTIN
유효한 피연산자:

EQ, NOTEQ: 피연산자는 문자열이어야 합니다.
IN, NOTIN: 피연산자는 ["value 1", "value 2", "value N"]와 같은 문자열 배열이어야 합니다.

정수 태그

유효한 연산자: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
유효한 피연산자:

EQ, NOTEQ, GTE, LTE: 피연산자는 정수여야 합니다.
IN, NOTIN: 피연산자는 [value 1, value 2, value N]와 같은 정수 배열이어야 합니다.
BETWEEN: 피연산자는 [min_value, max_value]와 같은 정수 배열이어야 합니다.

날짜 태그

유효한 연산자: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
유효한 피연산자:

"YYYY-MM-DD 00:00" (문자열)
유닉스 타임스탬프 1234567890 (정수)
연산자 EQ, BETWEEN, GTE, LTE의 경우 "N days ago" (문자열)

불리언 태그

유효한 연산자: EQ
유효한 피연산자: 0, 1, true, false

목록 태그

유효한 연산자: IN
유효한 피연산자: 피연산자는 ["value 1", "value 2", "value N"]와 같은 문자열 배열이어야 합니다.

registerEmail

앱에 이메일 주소를 등록합니다.

POST https://api.pushwoosh.com/json/1.3/registerEmail

요청 헤더

이름	필수	값	설명
Authorization	예	Token `XXXX`	Device API에 액세스하기 위한 API 디바이스 토큰입니다. `XXXX`를 실제 디바이스 API 토큰으로 바꾸세요.

요청 본문

이름	타입	설명
application*	string	Pushwoosh 애플리케이션 코드
email*	string	이메일 주소.
language	string	기기의 언어 로케일입니다. ISO-639-1 표준에 따른 소문자 두 글자 코드여야 합니다.
userId	string	이메일 주소와 연결할 사용자 ID입니다.
tz_offset	integer	초 단위의 시간대 오프셋입니다.
tags	object	등록된 기기에 할당할 태그 값입니다.

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "request": {
    "application": "APPLICATION_CODE",   // required. Pushwoosh application code.
    "email":"email@domain.com",          // required. Email address to be registered.
    "language": "en",                    // optional. Language locale.
    "userId": "userId",                  // optional. User ID to associate with the email address.
    "tz_offset": 3600,                   // optional. Timezone offset in seconds.
    "tags": {                            // optional. Tag values to set for the device registered.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // sets the list of values for Tags of List type
       "DateTag": "2024-10-02 22:11",    // note the time should be in UTC
       "BooleanTag": true                // valid values are: true, false
    }
  }
}

deleteEmail

사용자 기반에서 이메일 주소를 제거합니다.

POST https://api.pushwoosh.com/json/1.3/deleteEmail

요청 헤더

이름	필수	값	설명
Authorization	예	Token `XXXX`	Device API에 액세스하기 위한 API 디바이스 토큰입니다. `XXXX`를 실제 디바이스 API 토큰으로 바꾸세요.

요청 본문

이름	타입	설명
application	string	Pushwoosh 애플리케이션 코드
email	string	`/registerEmail` 요청에서 사용된 이메일 주소입니다.

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "request": {
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code
    "email": "email@domain.com"         // required. Email to delete from app subscribers.
  }
}

setEmailTags

이메일 주소에 대한 태그 값을 설정합니다.

POST https://api.pushwoosh.com/json/1.3/setEmailTags

요청 헤더

이름	필수	값	설명
Authorization	예	Token `XXXX`	Device API에 액세스하기 위한 API 디바이스 토큰입니다. `XXXX`를 실제 디바이스 API 토큰으로 바꾸세요.

요청 본문

이름	타입	설명
application	string	Pushwoosh 애플리케이션 코드
email	string	이메일 주소.
tags	object	설정할 태그의 JSON 객체, 값을 제거하려면 ‘null’을 보냅니다.
userId	string	이메일 주소와 연결된 사용자 ID입니다.

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "skipped": []
  }
}

{
  "request": {
    "email": "email@domain.com",                  // required. Email address to set tags for.
    "application": "APPLICATION_CODE",            // required. Pushwoosh application code.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // time in UTC
      "BooleanTag": true                          // valid values are: true, false
    },
    "userId": "userId"                            // optional. User ID associated with the email address.
  }
}

registerEmailUser

외부 사용자 ID를 지정된 이메일 주소와 연결합니다.

POST https://api.pushwoosh.com/json/1.3/registerEmailUser

/createEmailMessage API 호출(‘users’ 파라미터)에서 사용할 수 있습니다.

요청 헤더

이름	필수	값	설명
Authorization	예	Token `XXXX`	Device API에 액세스하기 위한 API 디바이스 토큰입니다. `XXXX`를 실제 디바이스 API 토큰으로 바꾸세요.

요청 본문

이름	타입	설명
application*	string	Pushwoosh 애플리케이션 코드
email*	string	이메일 주소.
userId*	string	이메일 주소와 연결할 사용자 ID입니다.
tz_offset	integer	초 단위의 시간대 오프셋입니다.

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "status_code": 400,
  "status_message": "Request format is not valid."
}

{
  "status_code": 403,
  "status_message": "Forbidden."
}

{
  "request": {
    "application": "APPLICATION_CODE", // required. Pushwoosh application code.
    "email": "email@domain.com",       // required. User email address.
    "userId": "userId",                // required. User ID to associate with the email address.
    "tz_offset": 3600                  // optional. Timezone offset in seconds.
  }
}