> ## 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 البريد الإلكتروني للحالة المقبولة أو المرفوضة الذي يتلقاه الشخص، مع المستلم والمرسل واللغة، قبل تغيير حالة الجلسة.
موجّه معاينة بريد قرار الجلسة
نسخ الموجّه إلى الحافظة
\
\`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": "",
"send_email": true,
"email_address": "",
"email_language": "",
"email_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//decision-email-preview/ \
-H "x-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.`
\
الصق في
تُجري المعاينة ولا تغيّر شيئاً ولا ترسل شيئاً.
تعرض الاستجابة البريد الإلكتروني كما يستلمه الشخص تماماً عند تعيين الجلسة إلى `Approved` أو `Declined` مع `send_email: true`.
كما تُبيّن لك من سيستلمه، ومن مُرسله، وما إذا كان تأكيد التغيير سيرسله أصلاً.## من يستلم البريد الإلكترونييُرسَل البريد الإلكتروني إلى عنوان الشخص نفسه، وهو العنوان الذي تحقق منه في خطوة التحقق من البريد الإلكتروني ضمن التدفق، وإلا فالعنوان المذكور في `contact_details` عند إنشاء الجلسة.
يحدد `recipient_source` المصدر المستخدَم (`email_verification` أو `contact_details`).
عندما لا يتوفر عنوان بريد إلكتروني للشخص في الجلسة، تكون قيم `recipient` و`recipient_source` و`preview_token` سلاسل نصية فارغة، ولا يمكن إرسال أي بريد إلكتروني.يُرسَل البريد الإلكتروني من نطاق المرسل المُتحقَّق منه في تطبيقك عندما ينطبق [إعداد العلامة البيضاء](https://docs.didit.me/ar/console/white-label.md) الخاص بك (`sender_kind: customer`)، وإلا فمن مرسل Didit (`sender_kind: didit`).## هل سيُرسَل البريد الإلكترونيتكون قيمة `will_be_sent` مساوية لـ `true` عندما يؤدي تأكيد التغيير مع `send_email: 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/ar/integration/sandbox-testing.md#رموز-otp-والاشتراك-في-البريد-الإلكتروني). |## تأكيد القراراستدعِ [تحديث حالة الجلسة](https://docs.didit.me/ar/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/ar/sessions-api/update-status.md): الموافقة على الجلسة أو رفضها وإرسال البريد الإلكتروني.
- [معاينة بريد إعادة التقديم](https://docs.didit.me/ar/sessions-api/preview-resubmission.md): معاينة البريد الإلكتروني الخاص بإعادة التقديم بدلاً من ذلك.
- [العلامة البيضاء](https://docs.didit.me/ar/console/white-label.md): المرسل والعلامة التجارية اللذان يستخدمهما البريد الإلكتروني.
## OpenAPI
````yaml ar/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: >-
عرض البريد الإلكتروني الذي يتلقاه الشخص عندما تقوم بتعيين الجلسة على
`Approved` أو `Declined` مع `send_email: true`، دون تغيير الجلسة أو
إرسال أي شيء. تُظهر الاستجابة الموضوع وكود HTML تماماً كما يتم إرسالهما،
والمستلم، والمُرسِل، واللغة، وما إذا كان تأكيد التغيير سيؤدي إلى إرسال
البريد الإلكتروني على الإطلاق (`will_be_sent`، `not_sent_reason`).
المستلم هو عنوان الشخص نفسه: العنوان الذي تحقق منه في خطوة التحقق من
البريد الإلكتروني ضمن سير العمل، أو العنوان المقدم في `contact_details`
عند إنشاء الجلسة. المُرسِل هو نطاق المُرسِل الذي تم التحقق منه لتطبيقك
عند تطبيق العلامة البيضاء (`sender_kind: customer`)، وإلا فإنه مُرسِل
Didit (`sender_kind: didit`).
لإرسال ما قمت بمعاينته تماماً، قم باستدعاء [Update Session
Status](/ar/sessions-api/update-status) مع نفس قيمة `new_status`،
و`send_email: true`، وتعيين `email_address` إلى `recipient`، وتعيين
`email_language` إلى `language`، وتعيين `email_preview_token` إلى
`preview_token`. ينتهي إيصال الاستلام بعد 15 دقيقة. إذا تغير المستلم، أو
اللغة، أو حالة الجلسة، أو المُرسِل، أو البريد الإلكتروني منذ المعاينة،
فإن التحديث يُرجع `409` قبل تغيير أي شيء؛ قم بالمعاينة مجدداً والتأكيد
باستخدام الإيصال الجديد.
يعمل مع جلسات التحقق من المستخدمين (KYC) والتحقق من الشركات (KYB) في
الحالات `Approved` أو `Declined` أو `In Review` أو `Kyc Expired` أو
`Abandoned` أو `Resubmitted`. يتم إجراء فحص الحالة قبل التحقق من صحة نص
الطلب. يتطلب امتياز `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).
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
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. اعرضه داخل إطار معزول، وتجنب
تماماً عرضه مباشرة في DOM الخاص بتطبيقك.
example: ...
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: >-
اللغة المكتوب بها البريد الإلكتروني. تكون الإنجليزية
(`en`) عندما لا تتوفر `email_language` التي طلبتها.
example: en
will_be_sent:
type: boolean
description: >-
ما إذا كان تأكيد التغيير باستخدام `send_email: true` يرسل
هذا البريد الإلكتروني. `false` عندما يكون
`not_sent_reason` معيناً.
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` إلى [تحديث
حالة الجلسة](/ar/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
sender_name: Example App
sender_email: no-reply@mail.example.com
sender_kind: customer
subject: Your verification has been approved in Example App
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
sender_name: Example App
sender_email: no-reply@mail.example.com
sender_kind: customer
subject: Your verification has been declined in Example App
html: ...
language: en
will_be_sent: false
not_sent_reason: no_recipient
preview_token: ''
'400':
description: >-
الجلسة ليست في حالة يقبلها هذا الـ endpoint (`{"detail": ...}`)، أو
جسم الطلب غير صالح (`{"": [""]}`).
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: لا توجد جلسة KYC أو KYB بمعرّف `session_id` هذا.
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: >-
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 الخاص بتطبيقك، من Developers -> API keys في Business Console.
يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا
شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات
المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن
المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم
إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو
الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير
404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة
بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL
للصور ومقاطع الفيديو وملفات PDF كـ 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.