跳转到主要内容
POST
curl

增值功能

将 enable_enrichment 设置为 true,即可同时对该邮箱地址进行邮箱情报分析,包括风险评分和泄露历史。 该附加功能按标准价格每次请求收取 $0.05,并在验证本身的价格之外另行计费。 当余额不足以支付该费用时,请求将返回 403。 有三个字段决定信号的处理方式。 每个字段的取值为 NO_ACTION(默认值)或 DECLINE,并且只有在 enable_enrichment 为 true 时才会生效。 设置为 NO_ACTION 时,信号仍会在 email.email_intelligence 中返回,便于您应用自己的规则。

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。

请求体

application/json
email
string<email>
必填

与匹配的 POST /v3/email/send/ 调用中使用的相同邮箱地址。这是将核验与发送关联起来的依据。

示例:

"alice@example.com"

code
string
必填

终端用户收到的一次性验证码:4–8 位数字,若发送时使用了 alphanumeric_code: true,则为 4–8 位字母/数字。比对不区分大小写。

Maximum string length: 10
示例:

"123456"

duplicated_email_action
enum<string>
默认值:NO_ACTION

当您应用的另一位用户(不同的 vendor_data)已经使用过相同地址并已通过验证(仅计入先前已通过的验证)时采取的操作。DECLINE 会将最终的 status 变为 Declined;NO_ACTION 会在 email.warnings 中记录该风险并填充 email.matches。

可用选项:
NO_ACTION,
DECLINE
breached_email_action
enum<string>
默认值:NO_ACTION

当地址出现在已知数据泄露事件中(email.is_breached)时的处理操作。DECLINE 会将最终 status 变为 Declined;NO_ACTION 会在 email.warnings 中记录该风险。

可用选项:
NO_ACTION,
DECLINE
disposable_email_action
enum<string>
默认值:NO_ACTION

当域名属于一次性/临时邮箱提供商(email.is_disposable)时采取的操作。DECLINE 会将最终的 status 变为 Declined;NO_ACTION 会在 email.warnings 中记录该风险。

可用选项:
NO_ACTION,
DECLINE
enable_enrichment
boolean
默认值:false

为 true 时,还会对该地址运行邮箱情报分析:风险评分及其数据泄露历史。除此 endpoint 本身的价格外,每次请求按单次 email_intelligence_api 计费(标价为 $0.05)。当您的余额不足以支付时,请求将返回 403。

示例:

false

email_intelligence_score_action
enum<string>
默认值:NO_ACTION

邮箱情报风险评分高于阈值时的操作。DECLINE 会将最终 status 翻转为 Declined;NO_ACTION 会记录该信号而不拒绝。仅在 enable_enrichment 为 true 时生效。

可用选项:
NO_ACTION,
DECLINE
recent_email_breach_action
enum<string>
默认值:NO_ACTION

当该地址出现在近期已知的数据泄露事件中时采取的操作。DECLINE 会将最终 status 更改为 Declined;NO_ACTION 仅记录该信号而不拒绝。仅在 enable_enrichment 为 true 时生效。

可用选项:
NO_ACTION,
DECLINE
frequent_email_breach_action
enum<string>
默认值:NO_ACTION

当该地址出现在多起已知的数据泄露事件中时采取的操作。DECLINE 会将最终 status 更改为 Declined;NO_ACTION 仅记录该信号而不拒绝。仅在 enable_enrichment 为 true 时生效。

可用选项:
NO_ACTION,
DECLINE
enable_social
boolean
默认值:false

为 true 时,还会查找该地址的社交足迹,即其注册所在的邮箱、社交、职业、电子商务和娱乐平台。除此 endpoint 本身的价格外,每次请求按一个 email_social 单位计费。

示例:

true

email_no_social_presence_action
enum<string>
默认值:NO_ACTION

社交足迹核查发现该地址在其覆盖的所有平台上均未注册时的操作。此 endpoint 仅接受 NO_ACTION 和 DECLINE;同名工作流配置键上提供 REVIEW。

可用选项:
NO_ACTION,
DECLINE

响应

核验已完成:错误的验证码和缺失的验证也会返回 200;请检查 status,而非 HTTP 状态码。email 仅在最终结果(Approved/Declined)中填充,在 Failed 时为 null,在 Expired or Not Found 时不存在。

request_id
string<uuid>

状态为 Approved/Declined 时:匹配验证的会话 ID,与 POST /v3/email/send/ 返回的 request_id 相同。状态为 Failed 和 Expired or Not Found 时:一个随机的一次性 UUID,后续无法查询。

status
enum<string>

Approved — 验证码正确,无拒绝风险。Declined — 最终状态:匹配到拒绝风险或尝试次数上限(3)已用尽。Failed — 验证码错误,仍有剩余尝试次数。Expired or Not Found — 在过去 5 分钟内该地址没有待处理的验证。

可用选项:
Approved,
Declined,
Failed,
Expired or Not Found
message
string

结果的便于人类阅读的说明,包括输入错误验证码后的剩余尝试次数。

email
object | null

完整邮箱报告。仅在已完成的结果(Approved/Declined)中存在(非 null);在 Failed 时为 null,在 Expired or Not Found 时不存在。

vendor_data
string | null

匹配验证会话的 vendor_data。若为 Expired or Not Found 则为 null。

metadata
object | null

匹配验证会话的 metadata。在 Expired or Not Found 时为 null。

created_at
string<date-time>

此检查响应的时间戳。

最后修改于 2026年11月7日