이메일 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"`. 생략하면 메시지는 트랜잭션으로 처리되어 제어 그룹을 포함한 모든 사람에게 전달됩니다. 마케팅 메시지는 제어 그룹 구성원에게 전달되지 않습니다.
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, treated as transactional: delivered to everyone.
                                        // Marketing messages are not delivered to control group members.
      "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": 210,
  "status_message": "Preset content is not approved",
  "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 (정수)
"N days ago" (문자열) 연산자 EQ, BETWEEN, GTE, LTE에 대해

불리언 태그

유효한 연산자: 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
}

{
  "status_code": 210,
  "status_message": "this hwid (email) is blacklisted",
  "response": null
}

{
  "status_code": 400,
  "status_message": "Missing required argument: email",
  "response": null
}

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

{
  "status_code": 500,
  "status_message": "Internal server error",
  "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
    }
  }
}

응답 코드

공개 API는 status_code로 결과를 반환합니다. 실패한 호출을 재시도해야 하는지 결정하려면 아래 표를 사용하세요.

`status_code`	의미	재시도?
`200`	성공 — 이메일 주소가 등록되었습니다.	아니요 — 완료됨.
`210`	인수/유효성 검사 오류 — 요청은 이해되었지만 거부되었습니다(블랙리스트 주소, 유효하지 않거나 일회용 이메일, 계정 플랜에 맞지 않는 플랫폼). 아래 210 오류 메시지를 참조하세요.	아니요 — 동일한 요청은 동일한 `210`을 반환합니다. 주소를 기록하고 건너뛰세요.
`400`	잘못된 형식의 요청 — 유효하지 않은 JSON 또는 필수 필드 누락.	아니요 — 요청을 수정하고 반복하지 마세요.
`403`	금지됨 — 유효하지 않거나 제한된 디바이스 API 토큰.	아니요 — 인증을 수정하세요.
`500`	내부 서버 오류 — 일시적인 인프라 문제 또는 시간 초과.	예, 지수 백오프 사용 — 유일한 일시적인 경우입니다.

210 오류 메시지

210 응답은 status_message에 구체적인 이유를 담고 있습니다.

`status_message`	의미
`this hwid (email) is blacklisted`	이 주소는 영구적인(하드) 반송 후 억제 목록에 있으며 다시 등록되지 않습니다.
`hwid (email) is invalid` / `has invalid semantic`	주소 유효성 검사에 실패했습니다.
`hwid (email) is empty`	주소가 제공되지 않았습니다.
`hwid (email) has invalid count of parts`	`@`가 누락되었거나 추가되었습니다.
`hwid (email) has invalid local part`	`@` 앞 부분이 유효하지 않습니다.
`hwid (email) has invalid domain part`	도메인 부분이 유효하지 않습니다.
`hwid (email) has disposable domain`	주소가 일회용/임시 이메일 도메인(예: 10minutemail)을 사용합니다.
`hwid is not valid`	`hwid` 자체가 잘못된 형식입니다.
`only email platform allowed for Email Only subscription`	계정이 이메일 전용 플랜에 있으며 이메일이 아닌 기기를 등록할 수 없습니다.

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