跳转到主要内容
POST
curl

授权

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

收件人邮箱地址。格式错误的地址返回 400;语法有效但无法接收邮件(DNS/MX 验证失败)的地址返回 200,且 status: "Undeliverable"。

示例:

"alice@example.com"

options
object

一次性验证码格式、本地化及品牌化选项。所有字段均为可选。

signals
object

关于终端用户的可选设备与网络信号,转发至反欺诈层以提升对滥用或自动化流量的检测能力。所有字段均为可选。

vendor_data
string

由调用方控制的可选标识符(您的内部用户 id、邮箱、UUID 等),在会话中持久化并在发送响应、匹配检查响应、Webhook 和 Business Console 中原样返回。可使用它将 Didit 的 request_id 与您的用户记录进行关联。

metadata
object | null

可选的自由格式 JSON 对象,持久化保存在会话中,并在发送响应、匹配检查响应、Webhook 以及 Business Console 中回显。

响应

已确认发送。请检查 status:Success 和 Retry 表示验证码正在发送中;Undeliverable 表示该地址无法接收邮件,且验证已最终确定为 Declined。request_id 是持久化的会话 ID(在 Retry 时 ID 相同)。

request_id
string<uuid>

验证的会话 id。Retry 发送会返回与原始发送相同的 request_id。此 id 会显示在 Business Console 中,在已完成的 POST /v3/email/check/ 中再次返回,并可传递给 GET /v3/session/{sessionId}/decision/。

status
enum<string>

Success:OTP 已通过邮件发送至新的验证(计费)。Retry:为先前发送创建的待处理验证重新发送了新的 OTP(免费)。Undeliverable:地址未通过可达性核验或消息无法发送;验证立即以 Declined 终结,且不产生计费。

可用选项:
Success,
Retry,
Undeliverable
reason
enum<string> | null

当 status 为 Undeliverable 时为 email_can_not_be_delivered;否则为 null。

可用选项:
email_can_not_be_delivered,
null
vendor_data
string | null

存储在会话中的 vendor_data 回显(来自首次发送)。

metadata
object | null

存储在会话中的 metadata 回显(来自首次发送)。

最后修改于 2026年11月7日