> ## 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.

# 预览决策邮件 API：已通过与已拒绝邮件

> 通过 Didit 预览用户将收到的已通过或已拒绝邮件，包括收件人、发件人和语言，并在更改会话状态前完成确认。



预览决策邮件提示词
        将提示词复制到剪贴板



      
      

\<pre>

\`Preview the Approved or Declined email a Didit session sends the person, then confirm the decision so exactly that email goes out.

Endpoint:
POST https://verification.didit.me/v3/session/{session_id}/decision-email-preview/

Authentication:
x-api-key (client API key) or a user-auth token. Privilege: write:sessions. A scoped API key needs write access to decisions.

Path parameter:
\- session_id (UUID): KYC or KYB; Didit resolves it against both session types.

Request body:
\- new_status (string, required): "Approved" or "Declined".
\- email_language (string, optional, default "en"): language of the email. A language that is not offered falls back to English.

The session's current status must be one of: Approved, Declined, In Review, Kyc Expired, Abandoned, Resubmitted.

Previewing changes nothing and sends nothing.

Response (200, Cache-Control: no-store):
\- recipient: the person's own address (the one they verified in the flow, else the one in contact_details). Empty string when none is known.
\- recipient_source: "email_verification", "contact_details", or "" when there is no address.
\- sender, sender_name, sender_email: the From header and its parts.
\- sender_kind: "customer" (your verified sender domain) or "didit" (Didit's sender).
\- subject, html: the email exactly as sent. Render html in a sandboxed frame.
\- language: the language actually used.
\- will_be_sent (boolean) and not_sent_reason: null, "status_unchanged", "notification_emails_disabled", "no_recipient" or "sandbox".
\- preview_token: receipt for this exact email, valid 15 minutes. Empty when there is no recipient.

Confirm with PATCH https://verification.didit.me/v3/session/{session_id}/update-status/:
\{
"new_status": "<same new_status>",
"send_email": true,
"email_address": "<recipient>",
"email_language": "<language>",
"email_preview_token": "<preview_token>"
}
If the recipient, language, session status, sender or email changed since the preview, or the receipt is older than 15 minutes, update-status returns 409 { "detail": "This email preview changed or expired. Preview the message again before confirming." } and changes nothing. Preview again and confirm with the new receipt.

curl example:
curl -X POST https://verification.didit.me/v3/session/<SESSION_ID>/decision-email-preview/ \
-H "x-api-key: <API_KEY>" \
-H "Content-Type: application/json" \
-d '{ "new_status": "Approved", "email_language": "en" }'

Failure modes:
\- 400: the session is not in an accepted status ({ "detail": "Only sessions with status ... can be updated. Current status: ..." }), or new_status is missing or invalid.
\- 401: the scoped API key has expired.
\- 403: missing credentials (a wrong, revoked or expired key gets 401), the caller lacks write:sessions, a scoped key lacks decisions write, or the session belongs to another application ({ "detail": "You do not have permission to perform this action." }).
\- 404: { "detail": "Not found." } when no session with this session_id exists.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\</pre>



      
      

粘贴到

预览不会更改任何内容，也不会发送任何邮件。
当你使用 `send_email: true` 将会话设置为 `Approved` 或 `Declined` 时，响应会显示用户实际收到的邮件内容。
响应还会告诉你邮件的收件人是谁、发件人是谁，以及确认后是否会真正发送邮件。## 谁会收到邮件邮件发送至用户本人的邮箱地址：即其在流程中完成邮箱验证步骤时验证过的地址；若没有，则使用创建会话时在 `contact_details` 中提供的地址。
`recipient_source` 说明适用的是哪一种（`email_verification` 或 `contact_details`）。
如果会话中没有该用户的邮箱地址，`recipient`、`recipient_source` 和 `preview_token` 均为空字符串，且无法发送邮件。当 [白标配置](https://docs.didit.me/zh/console/white-label.md) 生效时（`sender_kind: customer`），邮件从你应用已验证的发件域名发出；否则（`sender_kind: didit`）从 Didit 的发件人发出。## 邮件是否会发送当你使用 `send_email: true` 确认变更时，如果邮件会发送，则 `will_be_sent` 为 `true`。
当其为 `false` 时，`not_sent_reason` 会说明原因：| `not_sent_reason` | 含义 |
| - | - |
| `status_unchanged` | 会话已具有该状态，因此此次更新不会更改任何内容，也不会发送邮件。 |
| `notification_emails_disabled` | 创建会话时未设置 `contact_details.send_notification_emails: true`，因此不会向 `contact_details` 中提供的地址发送决策邮件。 |
| `no_recipient` | 无法获取该用户的邮箱地址。 |
| `sandbox` | 该会话为沙盒会话，且收件人未选择接收沙盒邮件，因此邮件只会被模拟。参见 [选择接收邮件](https://docs.didit.me/zh/integration/sandbox-testing.md#otp-验证码与邮件选择加入)。 |## 确认决策调用 [更新会话状态](https://docs.didit.me/zh/sessions-api/update-status.md)，并填写以下字段：| 更新会话状态字段 | 值 |
| - | - |
| `new_status` | 与你预览时相同的 `new_status` |
| `send_email` | `true` |
| `email_address` | 预览结果中的 `recipient` |
| `email_language` | 预览结果中的 `language` |
| `email_preview_token` | 预览结果中的 `preview_token` |回执在 15 分钟后过期。
如果自预览以来收件人、语言、会话状态、发件人或邮件内容发生了变化，更新会在任何内容被更改之前返回 `409`。
请重新预览，并使用新的回执进行确认。## 相关内容- [更新会话状态](https://docs.didit.me/zh/sessions-api/update-status.md)：批准或拒绝会话并发送邮件。
- [预览重新提交邮件](https://docs.didit.me/zh/sessions-api/preview-resubmission.md)：改为预览重新提交的邮件。
- [白标](https://docs.didit.me/zh/console/white-label.md)：邮件所使用的发件人和品牌设置。


## OpenAPI

````yaml zh/openapi-25.json POST /v3/session/{sessionId}/decision-email-preview/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/session/{sessionId}/decision-email-preview/:
    post:
      tags:
        - Sessions
      summary: 预览会话的决策电子邮件
      description: >-
        渲染当您使用 `send_email: true` 将会话设置为 `Approved` 或 `Declined`
        时该人员收到的电子邮件，而无需更改会话或发送任何内容。响应将准确显示发送的主题和
        HTML、收件人、发件人、语言，以及确认更改是否会真正发送电子邮件（`will_be_sent`、`not_sent_reason`）。


        收件人是该人员自己的地址：他们在工作流的邮箱验证步骤中核验的地址，或者是在创建会话时在 `contact_details`
        中提供的地址。发件人是在适用白标时您应用的已验证发件人域名（`sender_kind: customer`），否则为 Didit
        的发件人（`sender_kind: didit`）。


        要准确发送您预览的内容，请调用[更新会话状态](/zh/sessions-api/update-status)，传入相同的
        `new_status`、`send_email: true`、将 `email_address` 设置为
        `recipient`、`email_language` 设置为 `language` 并将 `email_preview_token` 设置为
        `preview_token`。凭证将在 15
        分钟后过期。如果收件人、语言、会话状态、发件人或电子邮件自预览以来发生更改，则更新将在发生任何更改之前返回
        `409`；请重新预览并使用新凭证进行确认。


        适用于处于 `Approved`、`Declined`、`In Review`、`Kyc Expired`、`Abandoned` 或
        `Resubmitted` 状态的用户验证（KYC）和企业验证（KYB）会话。状态检查在请求体验证之前运行。需要
        `write:sessions` 权限；受限 API 密钥需要对决策的写入权限。响应使用 `Cache-Control:
        no-store`：请将其视为敏感验证内容。
      operationId: post_v3_session_decision_email_preview
      parameters:
        - in: path
          name: sessionId
          required: true
          description: 验证会话的 UUID。支持用户（KYC）和企业（KYB）会话 ID。
          schema:
            type: string
            format: uuid
            example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - new_status
              properties:
                new_status:
                  type: string
                  enum:
                    - Approved
                    - Declined
                  description: 您想要预览其邮件的决策。
                  example: Approved
                email_language:
                  type: string
                  default: en
                  description: 邮件语言，默认值与“更新会话状态”相同。未提供的语言将回退为英语；响应中的 `language` 会指明所使用的语言。
                  example: en
            examples:
              Approved:
                summary: 预览英文版“已通过”电子邮件
                value:
                  new_status: Approved
              Declined in Spanish:
                summary: 预览西班牙语版“已拒绝”电子邮件
                value:
                  new_status: Declined
                  email_language: es
      responses:
        '200':
          description: 仅供预览。会话保持不变且不会发送电子邮件。
          headers:
            Cache-Control:
              description: 始终为 `no-store`：预览包含验证内容，切勿缓存。
              schema:
                type: string
                example: no-store
          content:
            application/json:
              schema:
                type: object
                required:
                  - recipient
                  - recipient_source
                  - sender
                  - sender_name
                  - sender_email
                  - sender_kind
                  - subject
                  - html
                  - text
                  - language
                  - will_be_sent
                  - not_sent_reason
                  - preview_token
                properties:
                  recipient:
                    type: string
                    description: >-
                      邮件发送的目标地址。若该人员无已知地址，则为空字符串：此时无法发送邮件，且 `preview_token`
                      同样为空。确认时请将其作为 `email_address` 传递。
                    example: person@example.com
                  recipient_source:
                    type: string
                    enum:
                      - email_verification
                      - contact_details
                      - ''
                    description: >-
                      `recipient`
                      的来源。`email_verification`：用户在流程的邮箱验证步骤中验证的地址。`contact_details`：创建会话时在
                      `contact_details` 中提供的地址。没有地址时为空字符串。
                    example: email_verification
                  sender:
                    type: string
                    description: 发送邮件时使用的 `From` 请求头。
                    example: Example App <no-reply@mail.example.com>
                  sender_name:
                    type: string
                    description: '`sender` 的显示名称部分。'
                    example: Example App
                  sender_email:
                    type: string
                    format: email
                    description: '`sender` 的地址部分。'
                    example: no-reply@mail.example.com
                  sender_kind:
                    type: string
                    enum:
                      - customer
                      - didit
                    description: '`customer`：邮件从您应用的已验证发送方域名发出（白标）。`didit`：从 Didit 自己的发送方发出。'
                    example: customer
                  subject:
                    type: string
                    description: 与发送时完全一致的主题行。
                    example: Your verification has been approved in Example App
                  html:
                    type: string
                    description: >-
                      发送时完全一致的电子邮件 HTML，其徽标作为 data URL 嵌入。请在沙盒 frame
                      中渲染，切勿直接在您的应用 DOM 中渲染。
                    example: <!DOCTYPE html><html><body>...</body></html>
                  text:
                    type: string
                    description: 电子邮件的纯文本内容，与该用户的“消息”会话中保留的一致，用于紧凑预览（HTML 仍为该用户收到的电子邮件形式）。
                    example: >-
                      Verification Approved


                      Your identity has been successfully verified with Acme
                      Pay. No further action is needed on your part.
                  language:
                    type: string
                    description: 邮件所用的语言。如果您请求的 `email_language` 不支持，则为英语（`en`）。
                    example: en
                  will_be_sent:
                    type: boolean
                    description: >-
                      使用 `send_email: true` 确认更改是否会发送此电子邮件。当设置了
                      `not_sent_reason` 时为 `false`。
                    example: true
                  not_sent_reason:
                    type: string
                    nullable: true
                    enum:
                      - status_unchanged
                      - notification_emails_disabled
                      - no_recipient
                      - sandbox
                      - null
                    description: >-
                      确认操作不会发送电子邮件的原因；若将发送邮件，则为
                      `null`。`status_unchanged`：会话已处于该状态，因此更新未做任何更改且不会发送任何内容。`notification_emails_disabled`：创建会话时未设置
                      `contact_details.send_notification_emails: true`，因此不会向
                      `contact_details`
                      中提供的地址发送决策电子邮件。`no_recipient`：未获取到该人员的地址。`sandbox`：属于沙盒会话且收件人未选择接收沙盒邮件投递，因此仅模拟发送。
                    example: null
                  preview_token:
                    type: string
                    description: >-
                      此特定邮件的签名收据，有效期为 15 分钟。将其作为 `email_preview_token`
                      传递给[更新会话状态](/zh/sessions-api/update-status)。当没有收件人时为空字符串。
                    example: >-
                      eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000
              examples:
                Will Be Sent:
                  summary: “已通过”邮件将发送至在流程中验证的邮箱地址
                  value:
                    recipient: person@example.com
                    recipient_source: email_verification
                    sender: Example App <no-reply@mail.example.com>
                    sender_name: Example App
                    sender_email: no-reply@mail.example.com
                    sender_kind: customer
                    subject: Your verification has been approved in Example App
                    html: <!DOCTYPE html><html><body>...</body></html>
                    language: en
                    will_be_sent: true
                    not_sent_reason: null
                    preview_token: >-
                      eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000
                No Recipient:
                  summary: 该人员没有已知的地址
                  value:
                    recipient: ''
                    recipient_source: ''
                    sender: Example App <no-reply@mail.example.com>
                    sender_name: Example App
                    sender_email: no-reply@mail.example.com
                    sender_kind: customer
                    subject: Your verification has been declined in Example App
                    html: <!DOCTYPE html><html><body>...</body></html>
                    language: en
                    will_be_sent: false
                    not_sent_reason: no_recipient
                    preview_token: ''
        '400':
          description: >-
            会话未处于此 endpoint 接受的状态（`{"detail": ...}`），或请求体无效（`{"<field>":
            ["<message>"]}`）。
          content:
            application/json:
              examples:
                Wrong Current Status:
                  summary: 会话不处于此 endpoint 接受的状态
                  value:
                    detail: >-
                      Only sessions with status Approved, Declined, In Review,
                      Kyc Expired, Abandoned, Resubmitted can be updated.
                      Current status: In Progress
                Invalid new_status:
                  summary: new_status 不是 Approved 或 Declined
                  value:
                    new_status:
                      - '"Resubmitted" is not a valid choice.'
                Missing new_status:
                  summary: 遗漏了必填字段
                  value:
                    new_status:
                      - This field is required.
        '401':
          description: 作用域 API 密钥已过期。
          content:
            application/json:
              examples:
                Expired API Key:
                  summary: 已过有效期的作用域 API 密钥
                  value:
                    detail: This API key has expired.
        '403':
          description: >-
            缺少凭据、调用方没有 `write:sessions` 权限、限定范围的 API 密钥缺少此 endpoint 所需的访问权限，或者
            `session_id` 属于另一个应用。
          content:
            application/json:
              examples:
                Invalid Credentials:
                  summary: x-api-key 缺失或无效
                  value:
                    detail: >-
                      Authentication credentials were not provided or are
                      invalid.
                Missing Privilege:
                  summary: 调用方缺少 write:sessions 权限
                  value:
                    detail: You do not have permission to perform this action.
                Scoped Key Without Access:
                  summary: 没有此访问权限的作用域 API 密钥
                  value:
                    detail: This API key has no write access to decisions.
        '404':
          description: 不存在具有此 `session_id` 的 KYC 或 KYB 会话。
          content:
            application/json:
              examples:
                Not Found:
                  summary: 未知的 session_id
                  value:
                    detail: Not found.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST \
              https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/decision-email-preview/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{"new_status": "Approved", "email_language": "en"}'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.sessions.preview_decision_email(
                "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                new_status="Approved",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: >-
            import Didit from "@didit-protocol/sdk-node";


            // Reads DIDIT_API_KEY.

            const didit = new Didit();


            const result = await
            didit.sessions.previewDecisionEmail("3fa85f64-5717-4562-b3fc-2c963f66afa6",
            {
              new_status: "Approved",
            });

            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.PreviewDecisionEmail(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.SessionsPreviewDecisionEmailParams{\n\tNewStatus: \"Approved\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.SessionsPreviewDecisionEmailParams;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.sessions().previewDecisionEmail("3fa85f64-5717-4562-b3fc-2c963f66afa6",
            SessionsPreviewDecisionEmailParams.builder()
                    .newStatus(SessionsPreviewDecisionEmailParams.NewStatus.of("Approved"))
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->sessions->previewDecisionEmail('3fa85f64-5717-4562-b3fc-2c963f66afa6',
            [
                'new_status' => 'Approved',
            ]);

            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.sessions.preview_decision_email(
              "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              new_status: "Approved"
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await
            client.Sessions.PreviewDecisionEmailAsync("3fa85f64-5717-4562-b3fc-2c963f66afa6",
            new SessionsPreviewDecisionEmailParams

            {
                NewStatus = "Approved",
            });

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

````

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