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

# 이메일 인증 경고 및 위험 코드

> Didit 이메일 인증의 모든 위험 코드(BREACHED_EMAIL_DETECTED, DISPOSABLE_EMAIL_DETECTED 등)와 차단 목록 및 OTP 한도에 대한 레퍼런스입니다.

이메일 인증 기능은 OTP 플로우나 주소 자체에서 위험 신호(알려진 데이터 침해, 일회용 이메일 제공업체, 수신 불가능한 편지함, OTP 시도 한도 초과, 차단 목록 또는 기존에 승인된 다른 인증과의 일치)가 발생할 때마다 **경고**를 생성합니다. 이 페이지에서는 모든 코드, 트리거 조건 및 워크플로 응답을 구성하는 방법을 설명합니다.

## 개요

경고에는 `EMAIL` 기능 태그가 지정됩니다. 보고서의 `email_verifications[].warnings[]` 아래에 표시되며 표준 [경고 객체](https://docs.didit.me/ko/reference/data-models.md#경고-객체) 형식(`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`)을 따릅니다. 또한 각 경고는 세션별 로그로 라우팅되어 Business Console의 이메일 섹션에 표시됩니다.

일부 경고는 **강제 자동 거부** 트리거로 작동합니다. 즉, 기능 상태를 항상 `Declined`로 설정하고 `log_type: "error"`를 포함합니다. 그 외 경고는 워크플로 노드별 또는 API 호출별로 정의되는 **구성 가능한 작업**(`DECLINE`, `REVIEW` 또는 기본값인 `NO_ACTION`)에 매핑되므로, 동일한 위험 코드라도 워크플로에 따라 거부되거나 플래그만 지정될 수 있습니다. 구성된 작업에 따라 심각도도 설정됩니다: `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

## 자동 거부 조건

다음 경고는 구성과 관계없이 이메일 인증 단계를 항상 거부합니다:

* `EMAIL_CODE_ATTEMPTS_EXCEEDED` — 사용자가 OTP 시도 한도를 소진했습니다. 기본적으로 2회의 잘못된 코드 입력(`email_max_check_attempts`) 또는 2회의 OTP 발송(최초 발송 1회 + 재전송 1회, `email_max_retries`)입니다.
* `EMAIL_IN_BLOCKLIST` — 주소가 [Lists API](https://docs.didit.me/ko/management-api/lists/overview.md)를 통해 관리되는 차단 목록에 포함되어 있거나, 이전에 승인된 이메일 인증 중 차단 목록에 등록된 항목과 일치합니다.
* `UNDELIVERABLE_EMAIL_DETECTED` — 잘못된 구문, 존재하지 않는 도메인, 누락된 DNS(MX) 레코드 등으로 주소에서 메일을 수신할 수 없거나, OTP 이메일이 전달되지 않았습니다. 이 단계는 코드 확인을 실행하지 않고 즉시 `Declined`로 종료됩니다. 예외: 사용자가 주소를 직접 입력한 경우(세션 생성 시 사전 입력되지 않음), 발송이 불가능하면 거부되는 대신 다른 주소로 재시도할 수 있도록 인라인 오류가 반환됩니다.

## 구성 가능한 위험

다음 각 위험은 `DECLINE`, `REVIEW` 또는 `NO_ACTION`으로 구성할 수 있는 설정(워크플로 노드별 또는 독립형 [검사 endpoint](https://docs.didit.me/ko/standalone-apis/email-check.md) 호출별)에 매핑됩니다:

| 설정 | 위험 코드 | 기본 동작 |
| - | - | - |
| `breached_email_action` | `BREACHED_EMAIL_DETECTED` | `NO_ACTION` — 상태 변경 없이 `information` 수준에서 데이터 침해 세부 정보를 표시합니다. |
| `disposable_email_action` | `DISPOSABLE_EMAIL_DETECTED` | `NO_ACTION` — 상태 변경 없이 `information` 수준에서 일회용 제공업체 플래그를 지정합니다. |
| `duplicated_email_action` | `DUPLICATED_EMAIL` | `NO_ACTION` — `information` 수준에서 중복을 기록합니다. 주소가 허용 목록에 있으면 건너뜁니다. |

중복 감지는 동일한 애플리케이션 내에서 **이전에 승인된** 이메일 인증만 고려하며, `vendor_data`를 기준으로 그룹화됩니다. 동일한 `vendor_data`를 공유하는 인증은 동일한 최종 사용자로 간주되어 제외됩니다. `vendor_data`를 비워 두면 모든 세션이 별개의 사용자로 처리됩니다. 해당 주소가 이메일 허용 목록에 있는 경우 중복 작업은 건너뛰고 대신 `EMAIL_IN_ALLOWLIST`가 생성됩니다.

## 인증 시도 한도

이메일 인증 기능은 오남용을 방지하기 위해 OTP 시도 횟수에 엄격한 한도를 적용합니다:

* **코드 입력 시도** — `email_max_check_attempts`, 기본값 **2**: 잘못된(또는 만료된) 코드가 두 번째 입력되면 단계가 종료됩니다.
* **발송 시도** — `email_max_retries`, 기본값 총 **2**회 발송(최초 발송 + 재전송 1회): 추가 재전송 요청이 발생하면 단계가 종료됩니다.

두 한도 중 하나라도 초과하면 `EMAIL_CODE_ATTEMPTS_EXCEEDED`가 발생하고 자동으로 거부됩니다. 두 한도 모두 워크플로 노드별로 조정할 수 있습니다.

## 생성되는 경고

| Tag | Severity | Description |
| - | - | - |
| `EMAIL_CODE_ATTEMPTS_EXCEEDED` | `error` | 사용자가 코드 입력 또는 전송 한도를 초과했습니다. 자동 거부됩니다. |
| `EMAIL_IN_BLOCKLIST` | `error` | 해당 주소가 [Lists API](https://docs.didit.me/ko/management-api/lists/overview.md)를 통해 생성된 차단 목록에 있거나, 차단 목록에 등록된 승인된 인증과 일치했습니다. 자동 거부됩니다. `additional_data`에는 `blocklisted_session_id`, `blocklisted_session_number`, `api_service`가 포함됩니다(순수 목록 일치의 경우 모두 `null`). |
| `EMAIL_IN_ALLOWLIST` | `information` | 해당 주소가 [Lists API](https://docs.didit.me/ko/management-api/lists/overview.md)를 통해 생성된 허용 목록과 일치하여 중복 이메일 작업을 건너뛰었습니다. |
| `BREACHED_EMAIL_DETECTED` | `breached_email_action`에 따름(기본값은 `information`) | 해당 주소가 하나 이상의 알려진 데이터 유출 사고에서 확인되었습니다. 보고서의 `breaches[]` 배열에는 정보 유출이 발생한 서비스, 날짜 및 데이터 클래스가 포함됩니다. |
| `DISPOSABLE_EMAIL_DETECTED` | `disposable_email_action`에 따름(기본값은 `information`) | 해당 도메인은 추적 가능성을 피하는 데 자주 사용되는 일회용/임시 이메일 제공업체로 알려져 있습니다. |
| `UNDELIVERABLE_EMAIL_DETECTED` | `error` | 해당 주소로 메일을 수신할 수 없습니다(유효하지 않은 구문, 존재하지 않는 도메인, 누락된 MX 레코드 또는 전송 실패). 자동 거부됩니다. |
| `DUPLICATED_EMAIL` | `duplicated_email_action`에 따름(기본값은 `information`) | 해당 주소가 다른 최종 사용자(`vendor_data`로 그룹화됨)의 이전에 승인된 이메일 인증과 일치합니다. `additional_data`에는 `duplicated_session_id`, `duplicated_session_number`, `api_service`가 포함됩니다. |

시도당 `EMAIL_IN_BLOCKLIST`, `DUPLICATED_EMAIL`, `EMAIL_IN_ALLOWLIST` 중 최대 하나만 발생하며, 차단 목록이 중복보다 우선하고, 중복이 허용 목록보다 우선합니다.

## 세션 간 일치

이전에 승인된 이메일 인증이나 차단 목록에서 주소가 감지되면 해당 일치 항목은 `email_verifications[].matches[]` 아래에도 표시됩니다(최대 5개 항목으로 제한). 각 일치 항목에는 `session_id`, `session_number`, `vendor_data`, `verification_date`, `email`, `status`, `is_blocklisted`, `api_service`, 그리고 `session`(다른 승인된 인증) 또는 `list_entry`(차단 목록 항목)인 `source`가 포함됩니다. 현재 주소가 이메일 허용 목록에 있는 경우, Didit은 일치 증거를 유지하지만 중복 이메일 작업을 적용하는 대신 `EMAIL_IN_ALLOWLIST`를 내보냅니다. 전체 일치 스키마는 [이메일 인증 보고서](https://docs.didit.me/ko/core-technology/email-verification/report-email-verification.md#세션-간-일치-항목)를 참고하십시오.

## 예시

```json theme={null}
{
  "warnings": [
    {
      "feature": "EMAIL",
      "risk": "EMAIL_IN_BLOCKLIST",
      "additional_data": {
        "blocklisted_session_id": null,
        "blocklisted_session_number": null,
        "api_service": null
      },
      "log_type": "error",
      "short_description": "Email in blocklist",
      "long_description": "The system detected that the email is in the blocklist, which is not allowed.",
      "node_id": "feature_email_1"
    },
    {
      "feature": "EMAIL",
      "risk": "DISPOSABLE_EMAIL_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "short_description": "Disposable email detected",
      "long_description": "The system detected that the email is disposable, which is not allowed.",
      "node_id": "feature_email_1"
    }
  ]
}
```

## 경고 유형

각 위험에는 애플리케이션 설정을 기반으로 심각도가 할당됩니다. 심각도는 세 가지 범주로 나뉩니다.

## 관련 문서

* [이메일 인증 개요](https://docs.didit.me/ko/core-technology/email-verification/overview.md) — 기능 동작 방식 및 요금.
* [이메일 인증 보고서](https://docs.didit.me/ko/core-technology/email-verification/report-email-verification.md) — `lifecycle[]` 및 `matches[]`를 포함한 전체 응답 형태.
* [데이터 모델 — 이메일 인증](https://docs.didit.me/ko/reference/data-models.md#이메일-인증) — 표준 필드별 스키마.
* [Management API — 목록](https://docs.didit.me/ko/management-api/lists/overview.md) — `EMAIL_IN_BLOCKLIST`에서 사용하는 이메일 차단 목록을 관리합니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.