跳转到主要内容
POST
curl
当您需要获取邮箱情报,但不希望用户输入一次性验证码时,请使用 POST /v3/email/risk/。 它不会发送邮件。它会创建一个 API 会话,丰富该地址的信息,应用您的邮箱风险规则,并在一次同步响应中返回与邮箱验证相同的标准化邮箱数据块。 保存请求后,Didit 还可以将评分后的邮箱作为汇总证据用于 网络。网络图谱可能会在共享邮箱信号上显示高风险邮箱情报、数据泄露背景以及社交资料覆盖情况,但不会向其他机构披露原始邮箱地址。

解读响应

  • status 是本次 API 会话的最终决策。通常为 Approved(已通过);风险评估也可能得出 In Review(审核中)或 Declined(已拒绝)。
  • email.is_breached、email.is_disposable 和 email.is_undeliverable 是供应用逻辑使用的稳定是/否信号。
  • email.breaches 在有覆盖数据时列出包含该地址的最近已知数据泄露记录,包括泄露日期和暴露的数据类别。
  • email.email_intelligence.score 采用 0-100 的风险评分,数值越高表示风险越高。breach_risk_level(Low、Medium、High)和 no_of_breaches 是派生视图。
  • email.email_intelligence.reason_codes 说明哪些标准化信号影响了结果。这些代码的取值可能随时间增加,因此请勿拒绝未知代码。
  • email.email_intelligence 和 email.enrichment 是兼容性别名,指向同一个标准化对象。新集成可以读取 email.enrichment。
  • email.matches 列出您应用中同一地址被其他用户使用的其他会话,可用于重复账户检测。
  • request_id 即 API 会话 ID。如需将结果与后续 Webhook 或控制台活动关联,请将其与 vendor_data 一同存储。
email.email_intelligence 和 email.enrichment 属于尽力返回的字段。当该地址、域名或套餐没有可用的情报数据时,即使查询已完成,这两个字段也可能缺失。请优先基于 is_breached、is_disposable 和 is_undeliverable 构建规则,并将缺失的情报视为”未知”,而非”安全”。

社交足迹附加功能

将 enable_social 设为 true,即可在 email 下的响应中添加 email_social 数据块。该数据块列出此邮箱地址注册过的在线平台,按类别分组,并附带汇总计数,以及数据合作伙伴返回的任何资料详情。
  • email.email_social.profiles_registered 和 email.email_social.profiles_checked 是核心数字:前者是已确认注册该邮箱的平台数,后者是所评估的平台总数。
  • email.email_social.registered_platforms 和 email.email_social.not_registered_platforms 分别列出每个平台及其 category 和 scope(global 表示全球平台,local 表示特定地区的平台)。
  • email.email_social.categories 给出每个类别的注册数量和比例。当平台提供资料时,email.email_social.profiles 会包含每个平台的资料详情(名称、头像 URL、简介文本、隐私状态以及是否为企业账户)。
  • 汇总指数(digital_footprint_diversity、digital_sophistication_index、engagement_depth_index、subscription_affordability_index)是 0-10 的综合评分。当检查未返回相应数据时,任何计数都可能为 null。
profiles_registered: 0 是一个真实结果,而不是失败:平台已经过检查,但该邮箱地址未在任何平台上找到,这是常见的合成身份信号。此接口本身不会据此采取行动。如需将其转化为审核或拒绝判定,请在工作流中使用 email_no_social_presence_action。 未设置 enable_social 时,响应中不会包含该数据块;社交检查无法完成时同样不会返回,且此时不计费。

沙盒行为

沙盒密钥会验证请求,并返回确定性的已通过数据。它们不会发送邮件、消耗额度、创建会话,也不会向网络贡献数据。设置 enable_social 后,沙盒还会返回确定性的 email_social 数据块。

计费

Email Risk API 调用的标价为 $0.04。由于不发送邮件,其费用低于完整的邮箱验证。一次真实请求在查询开始后即计费,即使部分尽力返回的字段不可用也不例外。 社交足迹附加功能单独计费:每次请求在 Email Risk API 价格之外,额外收取一个 email_social 单位,前提是检查已完成。查询前的额度检查同时覆盖这两项费用。

授权

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>
必填

要进行评分的邮箱地址。

示例:

"alice@example.com"

country_code
string

用于情报覆盖范围的可选 ISO 3166-1 alpha-2 或 alpha-3 国家/地区提示。

Maximum string length: 3
示例:

"US"

signals
object

您的应用所观测到的可选设备和网络上下文。所有字段均为可选。传入这些字段有助于为 Networks 中的跨会话匹配检测提供数据。

vendor_data
string

您为此请求提供的稳定引用。存储在 API 会话中并在响应中返回。

metadata
object | null

您的非敏感 JSON 元数据。存储在 API 会话中并在响应中原样返回。

enable_social
boolean
默认值:false

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

示例:

true

响应

风险评估已完成。检查 status 获取决策;对于已完成的查询,HTTP 状态码始终为 200。

request_id
string<uuid>
必填

为此请求创建的 API 会话 ID。如果您需要将结果与后续的 Webhook 或控制台活动关联,请将其与 vendor_data 一同存储。

status
enum<string>
必填

此 API 会话的最终决策。通常为 Approved;风险评估可能会产生 In Review 或 Declined。

可用选项:
Approved,
In Review,
Declined
created_at
string<date-time>
必填

此响应的时间戳。

vendor_data
string | null

您发送的 vendor_data 回显,若未发送则为 null。

metadata
object | null

您发送的 metadata 回显,若未发送则为 null。

email
object

归一化的邮箱报告,与邮箱验证响应所使用的区块相同。

最后修改于 2026年11月7日