Email API

createEmailMessage

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

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

Request body parameters

Name	Type	Required	Description
auth	`string`	예	Pushwoosh 컨트롤 패널의 API access token입니다.
application	`string`	예	Pushwoosh 애플리케이션 코드입니다.
notifications	`array`	예	이메일 메시지 세부 정보를 포함하는 JSON 배열입니다. 아래의 Notifications Parameters 표를 참조하십시오.

Notifications parameters

Name	Type	Required	Description
send_date	`string`	예	이메일을 보낼 시기를 정의합니다. 형식: `YYYY-MM-DD HH:mm` 또는 `"now"`.
preset	`string`	예	이메일 프리셋 코드입니다. Pushwoosh 컨트롤 패널의 Email Content Editor URL 표시줄에서 복사하십시오.
subject	`string` or `object`	아니요	이메일의 제목 줄입니다. 이메일은 항상 콘텐츠의 언어로 되어 있습니다. `subject`에 `content`와 일치하는 언어가 포함되어 있지 않으면 제목이 비어 있게 됩니다.
content	`string` or `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개)입니다. 사용되는 경우 메시지는 이 주소로만 전송됩니다. Application Group이 사용되는 경우 무시됩니다.
use_auto_registration	`boolean`	아니요	`true`인 경우 `devices` 매개변수의 이메일을 자동으로 등록합니다.
users	`array`	아니요	설정된 경우 이메일 메시지는 지정된 User ID들에게만 전달됩니다(/registerEmail 호출을 통해 등록됨). 배열 내 User ID는 1000개를 초과할 수 없습니다. “devices” 매개변수가 지정되면 “users” 매개변수는 무시됩니다.
dynamic_content_placeholders	`object`	아니요	디바이스 태그 값 대신 동적 콘텐츠를 위한 플레이스홀더입니다.
conditions	`array`	아니요	태그를 사용한 세그먼트화 조건입니다. 예: `[["Country", "EQ", "BR"]]`.
from	`object`	아니요	애플리케이션 속성의 기본값을 재정의하여 사용자 지정 발신자 이름과 이메일을 지정합니다.
reply-to	`object`	아니요	애플리케이션 속성의 기본값을 재정의하여 사용자 지정 회신 이메일을 지정합니다.
transactionId	`string`	아니요	네트워크 문제 발생 시 재전송을 방지하기 위한 고유 메시지 식별자입니다. 5분 동안 Pushwoosh 측에 저장됩니다.
capping_days	`integer`	아니요	디바이스당 빈도 제한(Frequency capping)을 적용할 일수(최대 30일)입니다. 참고: 컨트롤 패널에서 Global frequency capping이 구성되어 있는지 확인하십시오.
capping_count	`integer`	아니요	`capping_days` 기간 내에 특정 앱에서 특정 디바이스로 보낼 수 있는 최대 이메일 수입니다. 생성된 메시지가 디바이스의 `capping_count` 제한을 초과하는 경우 해당 디바이스로 전송되지 않습니다.
capping_exclude	`boolean`	아니요	`true`로 설정된 경우 이 이메일은 향후 이메일의 제한(capping)에 포함되지 않습니다.
capping_avoid	`boolean`	아니요	`true`로 설정된 경우 이 특정 이메일에는 제한(capping)이 적용되지 않습니다.
send_rate	`integer`	아니요	모든 사용자에게 초당 보낼 수 있는 메시지 수를 제한합니다. 대량 전송 중 백엔드 과부하를 방지하는 데 도움이 됩니다.
send_rate_avoid	`boolean`	아니요	`true`로 설정된 경우 이 특정 이메일에는 속도 제한(throttling limit)이 적용되지 않습니다.

Request example

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

Response examples

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

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

Tag conditions

각 태그 조건은 [tagName, operator, operand]와 같은 배열이며, 여기서:

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

Operand description

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

String tags

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

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

Integer tags

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

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

Date tags

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

"YYYY-MM-DD 00:00" (문자열)
unix timestamp 1234567890 (정수)
"N days ago" (문자열) - EQ, BETWEEN, GTE, LTE 연산자의 경우

Boolean tags

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

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

registerEmail

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

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

Request headers

Name	Required	Value	Description
Authorization	예	Token `XXXX`	Device API에 액세스하기 위한 API Device Token입니다. `XXXX`를 실제 Device API 토큰으로 교체하십시오.

Request body

Name	Type	Description
application*	string	Pushwoosh 애플리케이션 코드
email*	string	이메일 주소입니다.
language	string	디바이스의 언어 로케일입니다. ISO-639-1 표준에 따른 소문자 두 글자 코드여야 합니다.
userId	string	이메일 주소와 연결할 User 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

Request headers

Name	Required	Value	Description
Authorization	예	Token `XXXX`	Device API에 액세스하기 위한 API Device Token입니다. `XXXX`를 실제 Device API 토큰으로 교체하십시오.

Request body

Name	Type	Description
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

Request headers

Name	Required	Value	Description
Authorization	예	Token `XXXX`	Device API에 액세스하기 위한 API Device Token입니다. `XXXX`를 실제 Device API 토큰으로 교체하십시오.

Request body

Name	Type	Description
application	string	Pushwoosh 애플리케이션 코드
email	string	이메일 주소입니다.
tags	object	설정할 태그의 JSON 객체입니다. 값을 제거하려면 ‘null’을 보내십시오.
userId	string	이메일 주소와 연결된 User 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

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

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

/createEmailMessage API 호출(‘users’ 매개변수)에서 사용할 수 있습니다.

Request headers

Name	Required	Value	Description
Authorization	예	Token `XXXX`	Device API에 액세스하기 위한 API Device Token입니다. `XXXX`를 실제 Device API 토큰으로 교체하십시오.

Request body

Name	Type	Description
application*	string	Pushwoosh 애플리케이션 코드
email*	string	이메일 주소입니다.
userId*	string	이메일 주소와 연결할 User 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.
  }
}

Email API

createEmailMessage

Request body parameters

Notifications parameters

Request example

Response examples

Tag conditions

Operand description

String tags

Integer tags

Date tags

Boolean tags

List tags

registerEmail

Request headers

Request body

deleteEmail

Request headers

Request body

setEmailTags

Request headers

Request body

registerEmailUser

Request headers

Request body