> ## 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、UNDELIVERABLE_EMAIL_DETECTED、黑名单以及 OTP 上限等规则。

邮箱验证功能在 OTP 流程或邮箱地址本身触发风险信号时会发出**警告**：已知数据泄露、一次性邮箱服务商、无法送达的邮箱、达到 OTP 尝试上限，或命中黑名单或另一项已通过的验证。本页面列出了所有代码、触发条件以及如何配置工作流响应。

## 概述

警告标记有功能标识 `EMAIL`。它们显示在报告中的 `email_verifications[].warnings[]` 下，并遵循标准[警告对象](https://docs.didit.me/zh/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 发送，即初始发送加上一次重新发送（`email_max_retries`）。
* `EMAIL_IN_BLOCKLIST` — 该地址位于通过 [Lists API](https://docs.didit.me/zh/management-api/lists/overview.md) 管理的黑名单中，或匹配了之前被列入黑名单且已通过的邮箱验证。
* `UNDELIVERABLE_EMAIL_DETECTED` — 该地址无法接收邮件：语法无效、域名不存在、缺少 DNS (MX) 记录，或者 OTP 邮件无法送达。该步骤会立即以 `Declined` 结束，绝不会运行验证码核验。例外情况：当用户自行输入地址（在创建会话时未预填）时，无法送达的发送会返回内联错误，以便用户可以使用其他地址重试，而不会被拒绝。

## 可配置风险

以下每种风险都映射到一个设置（按工作流节点配置，或在独立的[核验 endpoint](https://docs.didit.me/zh/standalone-apis/email-check.md) 上按每次调用配置），您可以将其配置为 `DECLINE`、`REVIEW` 或 `NO_ACTION`：

| 设置 | 风险代码 | 默认行为 |
| - | - | - |
| `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** 次发送（初始发送加上一次重新发送）：后续的重新发送请求将结束该步骤。

超过任一上限都会引发 `EMAIL_CODE_ATTEMPTS_EXCEEDED` 并自动拒绝。您可以按工作流节点调整这两个上限。

## 生成的警告

| 标签 | 严重程度 | 描述 |
| - | - | - |
| `EMAIL_CODE_ATTEMPTS_EXCEEDED` | `error` | 用户超出了验证码输入或发送上限。自动拒绝。 |
| `EMAIL_IN_BLOCKLIST` | `error` | 该地址存在于通过 [Lists API](https://docs.didit.me/zh/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/zh/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/zh/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/zh/core-technology/email-verification/overview.md) — 功能行为与定价。
* [邮箱验证报告](https://docs.didit.me/zh/core-technology/email-verification/report-email-verification.md) — 包含 `lifecycle[]` 和 `matches[]` 的完整响应结构。
* [数据模型 — 邮箱验证](https://docs.didit.me/zh/reference/data-models.md#邮箱验证) — 规范的逐字段结构。
* [Management API — Lists](https://docs.didit.me/zh/management-api/lists/overview.md) — 管理供 `EMAIL_IN_BLOCKLIST` 使用的邮箱黑名单。


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