> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 이메일 주소 유효성 검사

> CSV 가져오기 중 및 일괄적으로 이메일 주소를 유효성 검사하여 반송을 줄이고 발신자 평판을 보호하세요.

이메일 주소 유효성 검사는 이메일 주소가 수신자에게 도달하기 전에 일반적인 문제를 감지합니다. 반송률을 높이거나 발신자 평판을 손상시킬 수 있는 오타, 유효하지 않은 도메인, 역할 기반 주소, 일회용 이메일 서비스를 표시합니다.

CSV 가져오기 중에 자동으로 실행되며 기존 수신자에 대한 일괄 검증 도구로도 사용할 수 있습니다.

<Note>
  이메일 주소 유효성 검사는 OneSignal의 검증 기준에 따라 주소를 확인합니다. 실시간 반송 검증 검사가 아니며 전달 가능성을 보장하지 않습니다.
</Note>

## 검증 항목

이메일 주소 유효성 검사는 다음 검사에 따라 각 주소를 평가합니다:

| 검사            | 감지 내용                                             |
| ------------- | ------------------------------------------------- |
| **구문 검증**     | 필수 구성 요소가 누락된 잘못된 형식의 주소 (예: `@` 누락, 유효하지 않은 TLD) |
| **오타 감지**     | `gnail.com` 또는 `gmail.con`과 같은 일반적인 도메인 철자 오류     |
| **MX 레코드 확인** | 유효한 메일 교환 레코드가 없는 도메인; 이 주소로는 이메일을 전달할 수 없음       |
| **역할 기반 주소**  | 개인에게 속할 가능성이 낮은 `sales@`, `info@`, `admin@` 등의 주소 |
| **일회용 이메일**   | 임시 또는 일회용 이메일 서비스와 관련된 도메인                        |

<Note>
  **무료 플랜**에는 구문 검증과 오타 감지가 포함됩니다. **유료 플랜**에는 위의 모든 기능과 함께 MX 레코드 확인, 역할 기반 주소 감지, 일회용 이메일 필터링이 포함됩니다.
</Note>

주소가 검사에 실패하면 이메일 주소 유효성 검사는 특정 문제를 설명하는 사람이 읽을 수 있는 오류를 반환합니다. 주소가 여러 검사에 실패하면 모든 실패 이유가 함께 반환되어 한 번에 모든 것을 처리할 수 있습니다.

***

## CSV 가져오기 중 주소 검증

CSV를 가져올 때 가져오기를 확인하기 전에 **검토** 단계에서 이메일 주소 유효성 검사 설정을 구성할 수 있습니다.

<Steps>
  <Step title="CSV 가져오기 시작">
    **수신자 > 가져오기**로 이동하여 파일을 업로드하세요. **업로드** 및 **필드 매핑** 단계를 완료하세요. 유효하지 않은 이메일 주소가 감지되면 **필드 매핑** 단계에 경고가 표시됩니다.

    <Frame caption="필드 매핑 단계의 유효하지 않은 이메일 감지 경고">
      <img src="https://mintcdn.com/onesignal/BtlAtFOavkYyZTGB/images/email/import_csv_invalid_email_detection.png?fit=max&auto=format&n=BtlAtFOavkYyZTGB&q=85&s=148ddc3343cca3ffddc8d6f3458a740a" alt="유효하지 않은 이메일 감지 경고를 보여주는 CSV 가져오기 필드 매핑 단계" width="1866" height="914" data-path="images/email/import_csv_invalid_email_detection.png" />
    </Frame>
  </Step>

  <Step title="검토 단계에서 검증 설정 구성">
    **검토** 단계에서 **이메일 주소 유효성 검사 설정**을 확장합니다. 다음 옵션을 사용할 수 있습니다:

    <Frame caption="검토 단계의 이메일 주소 유효성 검사 설정">
      <img src="https://mintcdn.com/onesignal/BtlAtFOavkYyZTGB/images/email/import_csv_validation_check.png?fit=max&auto=format&n=BtlAtFOavkYyZTGB&q=85&s=580a816aea94d087613178d392eee234" alt="이메일 주소 유효성 검사 설정이 확장된 CSV 가져오기 검토 단계" width="1814" height="1382" data-path="images/email/import_csv_validation_check.png" />
    </Frame>

    * **이메일 도메인 검증 (MX 레코드)**: 도메인이 이메일을 수신할 수 있는지 확인
    * **일회용 이메일 주소 제외**: 참여도를 낮출 수 있는 임시 또는 일회용 주소 방지
    * **역할 기반 이메일 주소 제외**: 참여도가 낮은 경우가 많은 `info@` 또는 `support@` 같은 공유 주소 방지

    세 가지 모두 기본적으로 활성화되어 있습니다. 이번 가져오기에 적용하지 않으려는 항목은 체크 해제하세요.

    <Note>
      유효하지 않은 이메일 주소를 가져와야 하는 경우(예: 수신 거부 또는 구독 상태 업데이트), **유효하지 않은 이메일 주소 허용**을 체크하세요. 이렇게 하면 검증을 우회하고 모든 문자열을 이메일 주소로 허용합니다.
    </Note>
  </Step>

  <Step title="확인 및 가져오기">
    **확인 및 가져오기**를 클릭합니다. 가져오기가 완료되면 결과를 요약한 이메일을 받게 됩니다:

    * 추가된 구독
    * 수정된 구독
    * 가져오지 않은 행 (거부된 행 다운로드 링크 포함)
  </Step>
</Steps>

#### 결과

유효한 주소가 수신자에 추가됩니다. 가져오기가 완료되면 이메일을 받게 됩니다. 검증에 실패한 주소는 제외되며 결과 이메일의 링크에서 다운로드할 수 있습니다.

***

## 기존 수신자 일괄 검증

일괄 검증을 사용하여 OneSignal 수신자에 이미 있는 이메일 주소를 확인하세요. 결과는 CSV 내보내기 형태로 이메일로 받게 됩니다.

<Steps>
  <Step title="이메일 주소 검증 도구 열기">
    **수신자 > 구독**(또는 **수신자 > 사용자**)으로 이동하여 **사용자 업데이트/가져오기**를 클릭한 다음 **이메일 주소 검증**을 선택합니다.

    <Frame caption="사용자 업데이트/가져오기 메뉴의 이메일 주소 검증 옵션">
      <img src="https://mintcdn.com/onesignal/BtlAtFOavkYyZTGB/images/email/validate_emails_sub_page.png?fit=max&auto=format&n=BtlAtFOavkYyZTGB&q=85&s=13700c5faffd0a46acdff1b3d687805f" alt="이메일 주소 검증 옵션이 강조 표시된 사용자 업데이트/가져오기 드롭다운" width="560" height="254" data-path="images/email/validate_emails_sub_page.png" />
    </Frame>
  </Step>

  <Step title="검증 시작">
    모달에서 **검증 시작**을 클릭합니다. 앱의 모든 이메일 주소에 대해 이메일 주소 유효성 검사가 실행됩니다.

    <Frame caption="이메일 주소 검증 확인 모달">
      <img src="https://mintcdn.com/onesignal/YsI3AV6UZEH5Saz0/images/email/bulk_validation_modal.png?fit=max&auto=format&n=YsI3AV6UZEH5Saz0&q=85&s=ac498afd710057320ec00644f4e27d30" alt="검증 시작 버튼을 보여주는 이메일 주소 검증 모달" width="1144" height="560" data-path="images/email/bulk_validation_modal.png" />
    </Frame>
  </Step>

  <Step title="이메일로 결과 받기">
    검증이 완료되면 OneSignal로부터 **CSV 내보내기 다운로드** 링크가 포함된 이메일을 받게 됩니다. 링크는 72시간 동안 유효합니다. 이메일은 실패한 주소 수를 다음 항목별로 요약합니다:

    <Frame caption="분류 및 CSV 내보내기 다운로드 링크가 포함된 OneSignal 검증 결과 이메일">
      <img src="https://mintcdn.com/onesignal/BtlAtFOavkYyZTGB/images/email/errors%20email.png?fit=max&auto=format&n=BtlAtFOavkYyZTGB&q=85&s=8655e75c51f2d96dbdcb911a528f4e89" alt="검증 요약 및 CSV 내보내기 다운로드 버튼을 보여주는 OneSignal 결과 이메일" width="1510" height="1182" data-path="images/email/errors email.png" />
    </Frame>

    * 오타
    * 역할 기반 주소
    * 일회용 도메인
    * 유효하지 않은 MX 레코드
  </Step>

  <Step title="검토 및 재가져오기">
    CSV를 다운로드하고 표시된 주소를 검토합니다.

    <Frame caption="이메일 검증 결과 CSV 내보내기">
      <img src="https://mintcdn.com/onesignal/q67Fo0fbZTTYBU0c/images/email/csv-export-email-validation.png?fit=max&auto=format&n=q67Fo0fbZTTYBU0c&q=85&s=8db9d159b9da06d7f26f3d4097455f37" alt="email, reason, suggested_email, created_at, last_opened, last_clicked 열을 보여주는 CSV 내보내기" width="868" height="74" data-path="images/email/csv-export-email-validation.png" />
    </Frame>

    수신자를 정리하려면 수정되거나 처리된 주소로 새 CSV를 만들고 다음 열 형식 중 하나를 사용하여 재가져오기 하세요:

    | 목표           | 필수 열                  | 값                     |
    | ------------ | --------------------- | --------------------- |
    | 수정된 주소 재구독   | `email`, `subscribed` | `subscribed` = `yes`  |
    | 표시된 주소 구독 취소 | `email`, `subscribed` | `subscribed` = `no`   |
    | 표시된 주소 수신 거부 | `email`, `suppressed` | `suppressed` = `true` |
  </Step>
</Steps>

#### 결과

오류 유형별로 분류된 검증 결과 요약과 함께 표시된 주소의 CSV 내보내기가 포함된 이메일을 받게 됩니다.

***

## 검증 오류 참조

다음 오류가 검증 결과에 나타날 수 있습니다:

| 오류                  | 의미                                                                                       | 처리 방법                                  |
| ------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------- |
| **잘못된 입력**          | 주소 형식이 잘못되어 기본 구문 요구 사항을 충족하지 않습니다 (예: `@` 누락, 유효하지 않은 TLD).                             | 주소를 수정하거나 제거하세요.                       |
| **이메일 주소의 오타**      | 도메인에서 오타가 감지되었습니다. 인접한 열에 제안된 수정 사항이 표시됩니다.                                              | 제안된 수정 사항을 적용하거나 주소를 제거하세요.            |
| **MX 레코드를 찾을 수 없음** | 도메인에 유효한 메일 교환 레코드가 없습니다. 이 주소로 이메일을 전달할 수 없습니다.                                         | 주소를 제거하거나 수신 거부하세요.                    |
| **역할 기반 이메일 주소**    | 로컬 부분(`@` 앞)이 `sales@` 또는 `support@`와 같은 알려진 역할 기반 패턴과 일치합니다. 이러한 주소는 개인에게 속할 가능성이 낮습니다. | 주소가 사용 사례에 적합한지 검토한 다음 수신 거부하거나 제거하세요. |
| **일회용 이메일 주소**      | 도메인이 임시 또는 일회용 이메일 서비스와 관련이 있습니다.                                                        | 주소를 수신 거부하거나 제거하세요.                    |

***

## API 오류 응답

이메일 주소 유효성 검사는 API를 통해 제출된 주소에도 적용됩니다. 아래 섹션에서는 발생할 수 있는 오류 응답을 설명합니다.

<Note>
  API 검증은 이메일 주소 형식이 올바른지만 확인합니다. 오타, MX 레코드, 역할 기반 주소 또는 일회용 도메인은 확인하지 않습니다. 이러한 검사는 CSV 가져오기 및 일괄 검증 중에만 사용할 수 있습니다.
</Note>

### 이메일 보내기: 메시지 만들기

[메시지 만들기 엔드포인트](/reference/create-message)를 통해 하나 이상의 유효하지 않은 주소로 보낼 때, 유효하지 않은 주소는 전달에서 제외되고 `invalid_email_tokens` 아래에 반환됩니다.

```json theme={null}
{
  "id": "",
  "errors": {
    "invalid_email_tokens": ["invalid@email"]
  }
}
```

### 사용자 또는 구독 추가: 사용자 모델 API

[사용자 만들기](/reference/create-user) 또는 [구독 만들기](/reference/create-subscription) 엔드포인트를 통해 유효하지 않은 이메일로 사용자 또는 구독을 만들 때:

```json theme={null}
{
  "errors": [
    {
      "title": "Invalid `token` format for device type email"
    }
  ]
}
```

### 기기 추가: 레거시 Players API

[레거시 Players API](/reference/add-a-device)를 통해 유효하지 않은 이메일로 플레이어 레코드를 추가하거나 편집할 때:

```json theme={null}
{
  "success": false,
  "errors": ["[\"Identifier invalid format.\"]"]
}
```

<Warning>
  레거시 Players API는 더 이상 사용되지 않습니다. 더 설명적인 검증 오류를 받고 현재 기능에 액세스하려면 [사용자 모델 API](/reference/create-user)로 마이그레이션하세요.
</Warning>