跳转到主要内容
POST
curl
预览不会更改任何内容,也不会发送任何邮件。 当你使用 send_email: true 将会话设置为 Approved 或 Declined 时,响应会显示用户实际收到的邮件内容。 响应还会告诉你邮件的收件人是谁、发件人是谁,以及确认后是否会真正发送邮件。

谁会收到邮件

邮件发送至用户本人的邮箱地址:即其在流程中完成邮箱验证步骤时验证过的地址;若没有,则使用创建会话时在 contact_details 中提供的地址。 recipient_source 说明适用的是哪一种(email_verification 或 contact_details)。 如果会话中没有该用户的邮箱地址,recipient、recipient_source 和 preview_token 均为空字符串,且无法发送邮件。 当 白标配置 生效时(sender_kind: customer),邮件从你应用已验证的发件域名发出;否则(sender_kind: didit)从 Didit 的发件人发出。

邮件是否会发送

当你使用 send_email: true 确认变更时,如果邮件会发送,则 will_be_sent 为 true。 当其为 false 时,not_sent_reason 会说明原因:

确认决策

调用 更新会话状态,并填写以下字段: 回执在 15 分钟后过期。 如果自预览以来收件人、语言、会话状态、发件人或邮件内容发生了变化,更新会在任何内容被更改之前返回 409。 请重新预览,并使用新的回执进行确认。

相关内容

授权

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。

路径参数

sessionId
string<uuid>
必填

验证会话的 UUID。支持用户(KYC)和企业(KYB)会话 ID。

示例:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

请求体

application/json
new_status
enum<string>
必填

您想要预览其邮件的决策。

可用选项:
Approved,
Declined
示例:

"Approved"

email_language
string
默认值:en

邮件语言,默认值与“更新会话状态”相同。未提供的语言将回退为英语;响应中的 language 会指明所使用的语言。

示例:

"en"

响应

仅供预览。会话保持不变且不会发送电子邮件。

recipient
string
必填

邮件发送的目标地址。若该人员无已知地址,则为空字符串:此时无法发送邮件,且 preview_token 同样为空。确认时请将其作为 email_address 传递。

示例:

"person@example.com"

recipient_source
enum<string>
必填

recipient 的来源。email_verification:用户在流程的邮箱验证步骤中验证的地址。contact_details:创建会话时在 contact_details 中提供的地址。没有地址时为空字符串。

可用选项:
email_verification,
contact_details,
示例:

"email_verification"

sender
string
必填

发送邮件时使用的 From 请求头。

示例:

"Example App <no-reply@mail.example.com>"

sender_name
string
必填

sender 的显示名称部分。

示例:

"Example App"

sender_email
string<email>
必填

sender 的地址部分。

示例:

"no-reply@mail.example.com"

sender_kind
enum<string>
必填

customer:邮件从您应用的已验证发送方域名发出(白标)。didit:从 Didit 自己的发送方发出。

可用选项:
customer,
didit
示例:

"customer"

subject
string
必填

与发送时完全一致的主题行。

示例:

"Your verification has been approved in Example App"

html
string
必填

发送时完全一致的电子邮件 HTML,其徽标作为 data URL 嵌入。请在沙盒 frame 中渲染,切勿直接在您的应用 DOM 中渲染。

示例:

"<!DOCTYPE html><html><body>...</body></html>"

text
string
必填

电子邮件的纯文本内容,与该用户的“消息”会话中保留的一致,用于紧凑预览(HTML 仍为该用户收到的电子邮件形式)。

示例:

"Verification Approved\n\nYour identity has been successfully verified with Acme Pay. No further action is needed on your part."

language
string
必填

邮件所用的语言。如果您请求的 email_language 不支持,则为英语(en)。

示例:

"en"

will_be_sent
boolean
必填

使用 send_email: true 确认更改是否会发送此电子邮件。当设置了 not_sent_reason 时为 false。

示例:

true

not_sent_reason
enum<string> | null
必填

确认操作不会发送电子邮件的原因;若将发送邮件,则为 null。status_unchanged:会话已处于该状态,因此更新未做任何更改且不会发送任何内容。notification_emails_disabled:创建会话时未设置 contact_details.send_notification_emails: true,因此不会向 contact_details 中提供的地址发送决策电子邮件。no_recipient:未获取到该人员的地址。sandbox:属于沙盒会话且收件人未选择接收沙盒邮件投递,因此仅模拟发送。

可用选项:
status_unchanged,
notification_emails_disabled,
no_recipient,
sandbox,
null
示例:

null

preview_token
string
必填

此特定邮件的签名收据,有效期为 15 分钟。将其作为 email_preview_token 传递给更新会话状态。当没有收件人时为空字符串。

示例:

"eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000"

最后修改于 2026年11月7日