# 이메일 API

import { Badge } from '@astrojs/starlight/components';

<Aside type="caution" title="/createEmailMessage는 더 이상 사용되지 않습니다">
새로운 통합은 [Messaging API v2](/ko/developer/api-reference/messaging-api-v2/)를 사용해야 합니다 — `Notify`에 `platforms: ["EMAIL"]`과 [`email_payload`](/ko/developer/api-reference/messaging-api-v2/email-payload-reference/) 블록을 전달하세요. [마이그레이션 가이드](/ko/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createemailmessage)를 참조하세요.
</Aside>

## createEmailMessage <Badge text="더 이상 사용되지 않음" variant="caution" size="small" />

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

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

### 요청 본문 파라미터

| 이름 | 유형 <div style="width:80px"></div> | 필수 | 설명 |
|------|--------|:--------:|-------------|
| auth | `string` | 예 | Pushwoosh Control Panel의 [API 액세스 토큰](/ko/developer/api-reference/api-identifiers/#api-access-token)입니다. |
| application | `string` | 예 | [Pushwoosh 애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code) |
| notifications | `array` | 예 | 이메일 메시지 세부 정보가 포함된 JSON 배열입니다. 아래 **알림 파라미터** 표를 참조하세요. |

#### 알림 파라미터

| 이름 | 유형 <div style="width:50px"></div> | 필수 | 설명 |
|------|------|:--------:|-------------|
| send_date | `string` | 예 | 이메일을 보낼 시기를 정의합니다. 형식: `YYYY-MM-DD HH:mm` 또는 `"now"`. |
| preset | `string` | 예 | [이메일 프리셋 코드](/ko/developer/api-reference/api-identifiers/#email-content-code). 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` | 아니요 | 이메일을 특정 캠페인과 연결하기 위한 [캠페인 코드](/ko/developer/api-reference/api-identifiers/#campaign-code)입니다. |
| ignore_user_timezone | `boolean` | 아니요 | `true`인 경우, 사용자 시간대를 무시하고 이메일을 즉시 보냅니다. |
| timezone | `string` | 아니요 | 사용자의 시간대에 따라 이메일을 보냅니다. 예: `"America/New_York"`. |
| filter | `string` | 아니요 | [특정 필터 조건](/ko/developer/api-reference/api-identifiers/#segment--filter-name)과 일치하는 사용자에게 이메일을 보냅니다. |
| devices | `array` | 아니요 | 타겟 이메일을 보낼 이메일 주소 목록(최대 1000개)입니다. 사용될 경우, 메시지는 이 주소로만 전송됩니다. 애플리케이션 그룹이 사용되는 경우 무시됩니다. |
| use_auto_registration | `boolean` | 아니요 | `true`인 경우, `devices` 파라미터의 이메일을 자동으로 등록합니다. |
| users | `array` | 아니요 | 설정된 경우, 이메일 메시지는 지정된 [User ID](/ko/developer/api-reference/api-identifiers/#user-id) (/registerEmail 호출을 통해 등록됨)에만 전달됩니다. 배열에 1000개 이하의 User 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"`일 때 필수입니다. | [구독 환경설정 센터](/ko/product/messaging-channels/emails/email-preferences/)에 구성된 카테고리 이름 중 하나를 지정합니다(예: 뉴스레터, 프로모션, 제품 업데이트). |
| transactionId | `string` | 아니요 | 네트워크 문제 발생 시 재전송을 방지하기 위한 고유 메시지 식별자입니다. Pushwoosh 측에서 5분간 저장됩니다. |
| capping\_days | `integer` | 아니요 | 디바이스당 빈도 제한을 적용할 일수(최대 30일)입니다. **참고:** Control Panel에서 [전역 빈도 제한](/ko/product/messaging-channels/global-frequency-capping/)이 구성되었는지 확인하세요. |
| capping\_count | `integer` | 아니요 | `capping_days` 기간 내에 특정 앱에서 특정 디바이스로 보낼 수 있는 최대 이메일 수입니다. 생성된 메시지가 디바이스의 `capping_count` 제한을 초과하는 경우, 해당 디바이스로 전송되지 않습니다. |
| capping\_exclude | `boolean` | 아니요 | `true`로 설정하면, 이 이메일은 향후 이메일의 빈도 제한에 포함되지 않습니다. |
| capping\_avoid | `boolean` | 아니요 | `true`로 설정하면, 이 특정 이메일에는 빈도 제한이 적용되지 않습니다. |
| send\_rate | `integer` | 아니요 | 모든 사용자에 걸쳐 초당 보낼 수 있는 메시지 수를 제한합니다. 대량 발송 시 백엔드 과부하를 방지하는 데 도움이 됩니다. |
| send\_rate\_avoid | `boolean` | 아니요 | true로 설정하면, 이 특정 이메일에는 스로틀링 제한이 적용되지 않습니다. |
### 요청 예시
```json
{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // 필수. Pushwoosh Control Panel의 API 액세스 토큰
    "application": "APPLICATION_CODE",  // 필수. Pushwoosh 애플리케이션 코드.
    "notifications": [{
      "send_date": "now",               // 필수. YYYY-MM-DD HH:mm 또는 'now'
      "preset": "ERXXX-32XXX",          // 필수. Pushwoosh Control Panel의 이메일 콘텐츠 편집기 페이지
                                        //           URL 바에서 이메일 프리셋 코드를 복사하세요.
      "subject": {                      // 선택. 이메일 메시지 제목.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // 선택. 이메일 본문 콘텐츠.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // 선택. 이메일 첨부 파일
        "name": "image.png",            //           "name" - 파일 이름
        "content": "iVBANA...AFTkuQmwC" //           "content" - 파일의 base64 인코딩된 콘텐츠
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // 선택. "Link-Unsubscribe" 헤더에 대한 사용자 지정 URL을 설정할 수 있습니다.
      "campaign": "CAMPAIGN_CODE",      // 선택. 이 이메일 메시지를 특정 캠페인에 할당하려면
                                        //           여기에 캠페인 코드를 추가하세요.
      "ignore_user_timezone": true,     // 선택.
      "timezone": "America/New_York",   // 선택. 사용자 디바이스에 설정된 시간대에 따라
                                        //           메시지를 보내도록 지정합니다.
      "filter": "FILTER_NAME",          // 선택. 필터 조건을 충족하는 특정 사용자에게 메시지를 보냅니다.
      "devices": [                      // 선택. 타겟 이메일 메시지를 보낼 이메일 주소를 지정합니다.
        "email_address1",               //           배열에 1000개 이하의 주소를 포함할 수 있습니다.
        "email_address2"                //           설정된 경우, 메시지는 목록에 있는 주소로만 전송됩니다.
      ],                                //           애플리케이션 그룹이 사용되는 경우 무시됩니다.
      "use_auto_registration": true,    // 선택. "devices" 파라미터에 지정된 이메일을 자동으로 등록합니다.
      "users": [                        // 선택. 설정된 경우, 이메일 메시지는 지정된
        "userId1",                      //           사용자 ID(/registerEmail 호출을 통해 등록됨)에만 전달됩니다.
        "userId2"                       //           배열에 1000개 이하의 사용자 ID를 포함할 수 있습니다.
      ],                                //           "devices" 파라미터가 지정된 경우,
                                        //           "users" 파라미터는 무시됩니다.
      "dynamic_content_placeholders": { // 선택. 디바이스 태그 값 대신 동적 콘텐츠에 대한 플레이스홀더입니다.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // 선택. 세분화 조건, 아래 설명을 참조하세요.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // 선택. 발신자 이름과 발신자 이메일 주소를 지정하여
        "name": "alias from",           //           애플리케이션 속성에 설정된 기본 "보낸 사람 이름"과
        "email": "from-email@email.com" //           "보낸 사람 이메일"을 대체합니다.
      },
      "reply-to": {                     // 선택. 이메일 주소를 지정하여 애플리케이션 속성에
        "name": "alias reply to ",      //           설정된 기본 "회신 주소"를 대체합니다.
        "email": "reply-to@email.com"
      },
      "bcc": [                          // 선택. BCC: 다른 수신자에게 보이지 않게 사본을 받는 이메일 주소 배열입니다.
        "bcc1@example.com",
        "bcc2@example.com"
      ],
      "email_type": "marketing",        // 선택. "marketing" 또는 "transactional".
                                        // 생략하면 PW_ControlGroup: true인 사용자는 메시지를 받지 않습니다.
      "email_category": "category name",// email_type이 "marketing"일 때 필수. 카테고리 이름.
      "transactionId": "unique UUID",   // 선택. 네트워크 문제 발생 시 재전송을 방지하기 위한
                                        //           고유 메시지 식별자. Pushwoosh 측에서
                                        //           5분간 저장됩니다.
      // 빈도 제한 파라미터. Control Panel에서 전역 빈도 제한이 구성되었는지 확인하세요.
      // 빈도 제한은 트랜잭션 메시지에는 적용되지 않습니다.
      // "email_type"이 생략된 경우를 포함한 다른 모든 경우에는 빈도 제한이 적용됩니다.
      "capping_days": 30,               // 선택. 빈도 제한 일수 (최대 30일)
      "capping_count": 10,              // 선택. 특정 앱에서 특정 디바이스로 'capping_days' 기간 내에
                                        //           보낼 수 있는 최대 이메일 수. 생성된 메시지가
                                        //           디바이스의 'capping_count' 제한을 초과하면
                                        //           해당 디바이스로 전송되지 않습니다.
      "capping_exclude": true,          // 선택. true로 설정하면, 이 이메일은
                                        //           향후 이메일의 빈도 제한에 포함되지 않습니다.
      "capping_avoid": true,            // 선택. true로 설정하면, 이 특정 이메일에는
                                        //           빈도 제한이 적용되지 않습니다.
      "send_rate": 100,                 // 선택. 스로틀링 제한.
                                        //           모든 사용자에 걸쳐 초당 보낼 수 있는 메시지 수를 제한합니다.
                                        //           대량 발송 시 백엔드 과부하를 방지하는 데 도움이 됩니다.
      "send_rate_avoid": true,          // 선택. true로 설정하면, 이 특정 이메일에는
                                        //           스로틀링 제한이 적용되지 않습니다.
    }]
  }
}
```

### 응답 예시
<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>

<TabItem label="403">
```json
{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}
```
</TabItem>
</Tabs>

### 태그 조건

각 태그 조건은 `[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"]`와 같은 문자열 배열이어야 함.

<Aside type="danger">
"filter"와 "conditions" 파라미터는 함께 사용해서는 안 된다는 점을 기억하세요.\
또한, "devices" 파라미터가 동일한 요청에 사용되면 두 파라미터 모두 **무시됩니다**.
</Aside>

<Aside type="note">
**국가 및 언어 태그**

언어 태그 값은 [ISO-639-1](https://en.wikipedia.org/wiki/List\_of\_ISO\_639-1\_codes)에 따른 소문자 두 글자 코드입니다.\
국가 태그 값은 [ISO\_3166-2](https://en.wikipedia.org/wiki/ISO\_3166-2)에 따른 대문자 두 글자 코드입니다.\
예를 들어, 브라질에 있는 포르투갈어 사용 구독자에게 푸시 알림을 보내려면 다음 조건을 지정해야 합니다: `"conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]`
</Aside>

## registerEmail

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

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

#### 요청 헤더

| 이름 | 필수 | 값 | 설명 |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | 예 | Token `XXXX` | Device API에 액세스하기 위한 [API 디바이스 토큰](/ko/developer/api-reference/api-access-token/#device-api-token)입니다. `XXXX`를 실제 디바이스 API 토큰으로 교체하세요. |


#### 요청 본문

| 이름 | 유형 | 설명 |
| --------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| application\* | string | [Pushwoosh 애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code) |
| email\* | string | 이메일 주소. |
| language | string | 디바이스의 언어 로케일. ISO-639-1 표준에 따른 소문자 두 글자 코드여야 합니다. |
| userId | string | 이메일 주소와 연결할 [User ID](/ko/developer/api-reference/api-identifiers/#user-id)입니다. |
| tz\_offset | integer | 초 단위의 시간대 오프셋. |
| tags | object | 등록된 디바이스에 할당할 태그 값. |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
<TabItem label="210">
```json
{
  "status_code": 210,
  "status_message": "this hwid (email) is blacklisted",
  "response": null
}
```
</TabItem>
<TabItem label="400">
```json
{
  "status_code": 400,
  "status_message": "Missing required argument: email",
  "response": null
}
```
</TabItem>
<TabItem label="403">
```json
{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}
```
</TabItem>
<TabItem label="500">
```json
{
  "status_code": 500,
  "status_message": "Internal server error",
  "response": null
}
```
</TabItem>
</Tabs>

```json title="예시"
{
  "request": {
    "application": "APPLICATION_CODE",   // 필수. Pushwoosh 애플리케이션 코드.
    "email":"email@domain.com",          // 필수. 등록할 이메일 주소.
    "language": "en",                    // 선택. 언어 로케일.
    "userId": "userId",                  // 선택. 이메일 주소와 연결할 User ID.
    "tz_offset": 3600,                   // 선택. 초 단위의 시간대 오프셋.
    "tags": {                            // 선택. 등록된 디바이스에 설정할 태그 값.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // 리스트 유형의 태그에 대한 값 목록을 설정합니다.
       "DateTag": "2024-10-02 22:11",    // 시간은 UTC여야 합니다.
       "BooleanTag": true                // 유효한 값: true, false
    }
  }
}
```

#### 응답 코드

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

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

<Aside type="tip">
`500` 응답만 지수 백오프를 사용하여 재시도하세요 — 이것이 유일한 일시적인 경우입니다. `210`, `400` 또는 `403`은 최종적입니다: 서버가 요청을 이해하고 거부했으므로 변경 없이 반복하면 동일한 결과가 반환됩니다. 대신 주소를 기록하거나(`210`의 경우) 요청/토큰을 수정하세요(`400`/`403`의 경우).
</Aside>

#### 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` | 계정이 이메일 전용 플랜에 있으며 이메일이 아닌 디바이스를 등록할 수 없습니다. |

<Aside type="note">
**영구적인(하드) 반송**만 주소를 블랙리스트에 추가합니다. 소프트 반송 및 스팸 불만은 `registerEmail`을 차단하지 **않습니다** — `this hwid (email) is blacklisted`만이 수신 거부를 반영합니다.
</Aside>

## deleteEmail

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

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

#### 요청 헤더

| 이름 | 필수 | 값 | 설명 |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | 예 | Token `XXXX` | Device API에 액세스하기 위한 [API 디바이스 토큰](/ko/developer/api-reference/api-access-token/#device-api-token)입니다. `XXXX`를 실제 디바이스 API 토큰으로 교체하세요. |


#### 요청 본문

| 이름 | 유형 | 설명 |
| ----------- | ------ | --------------------------------------------- |
| application | string | [Pushwoosh 애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code) |
| email | string | [`/registerEmail`](/ko/developer/api-reference/email-api/#registeremail) 요청에 사용된 이메일 주소. |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
</Tabs>

```json title="예시"
{
  "request": {
    "application": "APPLICATION_CODE",  // 필수. Pushwoosh 애플리케이션 코드
    "email": "email@domain.com"         // 필수. 앱 구독자에서 삭제할 이메일.
  }
}
```

## setEmailTags

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

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

#### 요청 헤더

| 이름 | 필수 | 값 | 설명 |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | 예 | Token `XXXX` | Device API에 액세스하기 위한 [API 디바이스 토큰](/ko/developer/api-reference/api-access-token/#device-api-token)입니다. `XXXX`를 실제 디바이스 API 토큰으로 교체하세요. |

#### 요청 본문

| 이름 | 유형 | 설명 |
| ----------- | ------ | ------------------------------------------------------------- |
| application | string | [Pushwoosh 애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code) |
| email | string | 이메일 주소. |
| tags | object | 설정할 태그의 JSON 객체, 값을 제거하려면 'null'을 보내세요. |
| userId | string | 이메일 주소와 연결된 [User ID](/ko/developer/api-reference/api-identifiers/#user-id). |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "skipped": []
  }
}
```
</TabItem>
</Tabs>

```json title="예시"
{
  "request": {
    "email": "email@domain.com",                  // 필수. 태그를 설정할 이메일 주소.
    "application": "APPLICATION_CODE",            // 필수. Pushwoosh 애플리케이션 코드.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // UTC 시간
      "BooleanTag": true                          // 유효한 값: true, false
    },
    "userId": "userId"                            // 선택. 이메일 주소와 연결된 User ID.
  }
}
```

<Aside type="note">
다른 디바이스 유형의 경우 태그가 저장되지 않더라도 200 OK가 반환됩니다.
</Aside>

<Aside type="caution">
단일 `/setEmailTags` 요청에 50개 이상의 태그 값을 설정하지 마세요.
</Aside>

## registerEmailUser

외부 [User ID](/ko/developer/api-reference/api-identifiers/#user-id)를 지정된 이메일 주소와 연결합니다.

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



<Aside type="note">
이 메서드는 사용자 기반에 이메일 주소를 **등록하지 않습니다**; `/registerEmail` 요청으로 이미 등록된 이메일 주소에 User ID를 할당하는 데만 사용해야 합니다.
</Aside>

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

#### 요청 헤더

| 이름 | 필수 | 값 | 설명 |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | 예 | Token `XXXX` | Device API에 액세스하기 위한 [API 디바이스 토큰](/ko/developer/api-reference/api-access-token/#device-api-token)입니다. `XXXX`를 실제 디바이스 API 토큰으로 교체하세요. |


#### 요청 본문

| 이름 | 유형 | 설명 |
| --------------------------------------------- | ------- | ---------------------------------------------- |
| application\* | string | [Pushwoosh 애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code) |
| email\* | string | 이메일 주소. |
| userId\* | string | 이메일 주소와 연결할 [User ID](/ko/developer/api-reference/api-identifiers/#user-id). |
| tz\_offset | integer | 초 단위의 시간대 오프셋. |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>

<TabItem label="400">
```json
{
  "status_code": 400,
  "status_message": "Request format is not valid."
}
```
</TabItem>

<TabItem label="403">
```json
{
  "status_code": 403,
  "status_message": "Forbidden."
}
```
</TabItem>
</Tabs>

```json title="예시"
{
  "request": {
    "application": "APPLICATION_CODE", // 필수. Pushwoosh 애플리케이션 코드.
    "email": "email@domain.com",       // 필수. 사용자 이메일 주소.
    "userId": "userId",                // 필수. 이메일 주소와 연결할 User ID.
    "tz_offset": 3600                  // 선택. 초 단위의 시간대 오프셋.
  }
}
```

<Aside type="note">
소프트 반송, 하드 반송 및 이메일 불만에 대한 데이터(날짜, 이메일 주소, 각 반송 사유 포함)를 검색하려면 [BouncedEmails](/ko/developer/api-reference/statistics-api/message-statistics-api/#bouncedemails) 메서드를 사용하세요.
</Aside>