> ## 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. # تقرير التحقق من البريد الإلكتروني: الاختراقات ورمز OTP > حلل استجابات التحقق من البريد في Didit: دورة حياة OTP، والاختراقات، والبريد المؤقت وغير القابل للتسليم، والتطابقات عبر الجلسات، والتحذيرات. يلتقط تقرير التحقق من البريد الإلكتروني النتيجة الكاملة لتحدي OTP للبريد الإلكتروني: الجهة التي أُرسلت إليها الرسالة، وما إذا كان العنوان مؤقتاً أو غير قابل للتسليم، وما إذا كان يظهر في اختراقات بيانات معروفة، وعدد المحاولات التي أجراها المستخدم، وأي حالات تطابق عبر الجلسات مع قائمة الحظر الخاصة بك أو مع مستخدمين آخرين مقبولة بياناتهم. توثق هذه الصفحة هيكل JSON الذي يُرجعه endpoint القرار حتى تتمكن من تحليل نتائج OTP، والتعرض للاختراقات، ومؤشرات المخاطر لكل عنوان تم التحقق منه. ![Didit email verification report showing OTP outcome, breach data and risk flags](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/email-verification-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=4d153b7d3d9d4c88bc3932466af7ed29) ## نظرة عامة يتم إنشاء تقرير البريد الإلكتروني في كل مرة تُشغّل فيها عقدة سير العمل ميزة التحقق من البريد الإلكتروني. يمثل كل تقرير تحدي OTP واحداً لعنوان واحد ويحتوي على: * عنوان `email` الذي تم التحقق منه. * مؤشرات مخاطر منطقية (`is_breached` و`is_disposable` و`is_undeliverable`) ومصفوفة `breaches[]` الداعمة المستخرجة من قاعدة بيانات معلومات الاختراقات. * عدد محاولات إرسال OTP (`verification_attempts`) والطابع الزمني للموافقة. * سجل `lifecycle[]` زمني لكل محاولة إرسال وإعادة محاولة والتحقق من الرمز. * مصفوفة `matches[]` تُظهر نفس العنوان في عمليات تحقق مقبولة أخرى من البريد الإلكتروني أو في قائمة الحظر الخاصة بك. * مصفوفة `warnings[]` — أحداث مخاطر صادرة أثناء التحقق (انظر [تحذيرات التحقق من البريد الإلكتروني](https://docs.didit.me/ar/core-technology/email-verification/warnings-email-verification.md)). * معرّف `node_id` يحدد أي عقدة في مخطط سير العمل أنتجت التقرير (جلسات V3 فقط). في جلسات سير العمل المستضافة، يتم تشغيل تحدي OTP داخل واجهة مستخدم التحقق الخاصة بـ Didit — وما عليك سوى قراءة النتيجة من payload القرار. ولإجراء OTP من خادم إلى خادم بدون تدفق مستضاف، استخدم Email API المستقلة: يُسلّم endpoint [`POST /v3/email/send/`](https://docs.didit.me/ar/standalone-apis/email-send) الرمز ويتحقق endpoint [`POST /v3/email/check/`](https://docs.didit.me/ar/standalone-apis/email-check) من إدخال المستخدم؛ وتظهر عمليات التحقق المستقلة المكتملة من خلال نفس هيكل التقرير. تحدد الجلسات المستضافة الحد الأقصى للمستخدم افتراضياً بـ **إدخالين خاطئين للرمز** (`email_max_check_attempts`) و**مرتي إرسال لرمز OTP — الإرسال الأولي بالإضافة إلى إعادة إرسال واحدة** (`email_max_retries`)، وهو أمر قابل للتعديل لكل عقدة سير عمل. يؤدي تجاوز أي من الحدين إلى إنهاء الخطوة بحالة `Declined` مع `EMAIL_CODE_ATTEMPTS_EXCEEDED`. ## أين يظهر في استجابات API يُرجع endpoint القرار (`GET /v3/session/{sessionId}/decision/`) تقارير البريد الإلكتروني تحت مفتاح المصفوفة بصيغة الجمع **`email_verifications`**. تحتوي المصفوفة على إدخال واحد لكل عقدة تحقق من البريد الإلكتروني في مخطط سير العمل — عادة ما يكون إدخالاً واحداً، ولكن قد تُنتج تدفقات التصعيد عدة إدخالات. ```json theme={null} { "session_id": "11111111-1111-1111-1111-111111111111", "status": "Approved", "email_verifications": [ { "node_id": "feature_email_1", "status": "Approved", "...": "..." } ] } ``` تعني قيمة `null` أنه لم يتم تشغيل أي خطوة تحقق من البريد الإلكتروني بعد. اجتز عناصر المصفوفة (بدلاً من قراءة `email_verifications[0]`) عندما يكون بإمكان سير العمل الخاص بك جمع أكثر من عنوان بريد إلكتروني واحد. ## المخطط يوجد المخطط المرجعي الكامل، حقلاً بحقل، في صفحة [نماذج البيانات](https://docs.didit.me/ar/reference/data-models.md#التحقق-من-البريد-الإلكتروني). ```typescript theme={null} interface EmailVerification { node_id: string | null; status: "Not Finished" | "Approved" | "Declined" | "In Review" | "Expired"; email: string; is_breached: boolean; breaches: Breach[]; // Up to the 5 most recent known breaches is_disposable: boolean; // Disposable / throwaway provider is_undeliverable: boolean; // Failed syntax / DNS (MX) validation or OTP delivery verification_attempts: number; // OTP send attempts verified_at: string | null; // ISO 8601, null until a valid code is entered lifecycle: EmailLifecycleEvent[]; // OTP send/retry/check timeline warnings: Warning[]; // Risk events (see Data models → Warning object) matches: EmailMatch[]; // Cross-session / blocklist matches } interface Breach { name: string; // Breached service name domain: string; // Affected domain breach_date: string; // YYYY-MM-DD breach_emails_count: number; // Total affected accounts description: string; // HTML description of the breach logo_path: string; // Breached-service logo URL data_classes: string[]; // Exposed data categories (snake_case) is_verified: boolean; // true when the breach is a verified incident } ``` يؤدي العنوان غير القابل للتسليم — بسبب بنية غير صالحة، أو نطاق غير موجود، أو سجلات MX مفقودة، أو فشل في تسليم رمز OTP — إلى إنهاء الخطوة كـ **`Declined`** مع تحذير الرفض التلقائي `UNDELIVERABLE_EMAIL_DETECTED`. الاستثناء الوحيد: عندما يكتب المستخدم العنوان بنفسه (لم يتم ملؤه مسبقاً عند إنشاء الجلسة)، يُرجع الإرسال غير القابل للتسليم خطأً مضمناً حتى يتمكن من إعادة المحاولة باستخدام عنوان مختلف بدلاً من رفضه على الفور. ### قيم الحالة | الحالة | المعنى | | - | - | | `Not Finished` | بدأ إرسال رمز OTP ولكن لم يتم الانتهاء من التحقق بعد. | | `Approved` | أدخل المستخدم رمز OTP صالحاً ولم يتطابق أي خطر يؤدي إلى الرفض. | | `Declined` | تم إطلاق تحذير رفض تلقائي (قائمة الحظر، عنوان غير قابل للتسليم، تجاوز عدد المحاولات) أو انطبق إجراء مخاطر تم تكوينه على `DECLINE`. | | `In Review` | وجّه إجراء مخاطر تم تكوينه على `REVIEW` الخطوة إلى مراجعة يدوية. | | `Expired` | انقضت نافذة رمز OTP البالغة 5 دقائق دون رمز صالح — ينطبق على عمليات التحقق التي تم إنشاؤها عبر API البريد الإلكتروني المستقل. | ### أنواع أحداث دورة الحياة يتم ترتيب `lifecycle[]` ترتيباً زمنياً. يحتوي كل حدث على `type` و`timestamp` و`details` بالإضافة إلى `fee` قابلة للفوترة (عند الانطباق): | نوع الحدث | يُرسل عند | | - | - | | `EMAIL_VERIFICATION_MESSAGE_SENT` | المحاولة الأولى لإرسال رمز OTP — بما في ذلك عمليات الإرسال التي تُعاد بنتيجة عدم القابلية للتسليم. | | `EMAIL_VERIFICATION_RETRY_MESSAGE_SENT` | إرسال رمز OTP لاحق بعد أن طلب المستخدم إعادة الإرسال. | | `VALID_CODE_ENTERED` | قدّم المستخدم رمز OTP الصحيح. | | `INVALID_CODE_ENTERED` | قدّم المستخدم رمز OTP خاطئاً أو منتهي الصلاحية (يُحسب ضمن الحد الأقصى). | | `EMAIL_VERIFICATION_APPROVED` | تعيين حالة الميزة إلى `Approved`. | | `EMAIL_VERIFICATION_DECLINED` | تعيين حالة الميزة إلى `Declined`. | | `EMAIL_VERIFICATION_IN_REVIEW` | تعيين حالة الميزة إلى `In Review`. | | `EMAIL_VERIFICATION_EXPIRED` | انقضاء نافذة رمز OTP دون رمز صالح (API البريد الإلكتروني المستقل). | يعتمد payload الخاص بـ `details` على عائلة الحدث: * **أحداث الإرسال** (`EMAIL_VERIFICATION_MESSAGE_SENT`، `EMAIL_VERIFICATION_RETRY_MESSAGE_SENT`) — `{ status, reason }`. تكون قيمة `status` هي `Success` أو `Retry` أو `Undeliverable`؛ وتكون قيمة `reason` هي `null` ما لم يفشل الإرسال (`email_can_not_be_delivered`، أو `unknown` للقيم القديمة غير المعروفة). * **أحداث التحقق** (`VALID_CODE_ENTERED`، `INVALID_CODE_ENTERED`) — `{ code_tried, status }` مع `status` بقيمة `Approved` أو `Failed` أو `Expired or Not Found` أو `Declined`. * **أحداث الحالة النهائية** — `null`، باستثناء `EMAIL_VERIFICATION_DECLINED` / `EMAIL_VERIFICATION_IN_REVIEW`، والتي تحمل `{ "reason": "" }` (على سبيل المثال `UNDELIVERABLE_EMAIL_DETECTED`). تسجل عمليات الإرسال ذات `status` بقيمة `Success` أو `Undeliverable` رسوم التحقق من البريد الإلكتروني البالغة \$0.02؛ بينما تحمل عمليات إرسال `Retry` وأحداث التحقق وأحداث الحالة دائماً `fee: 0`. ### التطابقات عبر الجلسات تسجل مصفوفة `matches[]` العنوان نفسه في عمليات التحقق من البريد الإلكتروني **المقبولة سابقاً** في نفس التطبيق — عبر جلسات KYC وKYB وجلسات API المستقلة — بالإضافة إلى مطابقات قائمة الحظر التي تم تكوينها في [قوائم management-api](https://docs.didit.me/ar/management-api/lists/overview.md). يتم استبعاد عمليات التحقق التي تشترك في `vendor_data` للجلسة الحالية (المستخدم النهائي نفسه لا يطابق نفسه)، ويبلغ الحد الأقصى للمصفوفة **5** مدخلات، مرتبة من الأقدم إلى الأحدث. عندما يكون العنوان موجوداً في قائمة الحظر الخاصة بك ولكن لم يتم إدراج أي من الجلسات المتطابقة في قائمة الحظر، يُضاف إدخال تركيبي مع `source: "list_entry"` (جميع حقول الجلسة تكون `null`) في بداية المصفوفة. ```typescript theme={null} interface EmailMatch { session_id: string | null; // null when source = "list_entry" session_number: number | null; vendor_data: string | null; verification_date: string | null; // ISO 8601, creation date of the matched session email: string; status: string | null; // Status of the matched session is_blocklisted: boolean; api_service: string | null; // Set when the matched session came from a standalone API source: "session" | "list_entry"; // "list_entry" = manual blocklist hit } ``` ## أمثلة ### مقبولة — رمز OTP سليم مع خرق معلوماتي واحد ```json theme={null} { "node_id": "feature_email_1", "status": "Approved", "email": "alex.sample@example.com", "is_breached": true, "breaches": [ { "name": "ExampleAir", "domain": "example-air.com", "breach_date": "2022-08-25", "breach_emails_count": 6083479, "description": "In August 2022, the airline ExampleAir suffered a data breach that exposed customers' personal information.", "logo_path": "https:///logos/ExampleAir.png", "data_classes": [ "dates_of_birth", "email_addresses", "genders", "names", "nationalities", "phone_numbers", "physical_addresses", "salutations", "spoken_languages" ], "is_verified": true } ], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2025-09-15T17:36:19.963451Z", "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-09-15T17:35:50.000000+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2025-09-15T17:36:19.000000+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_APPROVED", "timestamp": "2025-09-15T17:36:19.963451+00:00", "details": null, "fee": 0 } ], "warnings": [ { "feature": "EMAIL", "risk": "BREACHED_EMAIL_DETECTED", "additional_data": null, "log_type": "information", "short_description": "Breached email detected", "long_description": "This email address was found in one or more known data breaches.", "node_id": "feature_email_1" } ], "matches": [] } ``` ### مرفوضة — عنوان غير قابل للتسليم ينتهي العنوان المملوء مسبقاً والذي يفشل في التحقق من صحة البنية أو DNS (MX) — أو الذي يتعذر تسليم بريد OTP إليه — على الفور كـ `Declined`. لا تظهر أي أحداث للتحقق من الرمز لأن الرمز لم يصل إلى المستخدم أبداً. ```json theme={null} { "node_id": "feature_email_1", "status": "Declined", "email": "user@nonexistent-domain.example", "is_breached": false, "breaches": [], "is_disposable": false, "is_undeliverable": true, "verification_attempts": 1, "verified_at": null, "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-09-15T18:00:00.000000+00:00", "details": { "status": "Undeliverable", "reason": "email_can_not_be_delivered" }, "fee": 0.02 }, { "type": "EMAIL_VERIFICATION_DECLINED", "timestamp": "2025-09-15T18:00:01.500000+00:00", "details": { "reason": "UNDELIVERABLE_EMAIL_DETECTED" }, "fee": 0 } ], "warnings": [ { "feature": "EMAIL", "risk": "UNDELIVERABLE_EMAIL_DETECTED", "additional_data": null, "log_type": "error", "short_description": "Undeliverable email detected", "long_description": "The system detected that the email is undeliverable, which is not allowed.", "node_id": "feature_email_1" } ], "matches": [] } ``` ### مرفوضة — صندوق بريد مؤقت مدرج في قائمة الحظر أكمل المستخدم عملية التحقق عبر OTP، لكن العنوان تطابق مع قائمة حظر البريد الإلكتروني الخاصة بك (رفض تلقائي). تم أيضاً رفع علامة البريد المؤقت — بمستوى `information` هنا لأن `disposable_email_action` تُرِك على قيمته الافتراضية `NO_ACTION`. ```json theme={null} { "node_id": "feature_email_1", "status": "Declined", "email": "user@mailinator.com", "is_breached": false, "breaches": [], "is_disposable": true, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2025-09-15T18:05:42.201734Z", "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-09-15T18:05:01.000000+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2025-09-15T18:05:42.000000+00:00", "details": { "code_tried": "654321", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_DECLINED", "timestamp": "2025-09-15T18:05:42.201734+00:00", "details": { "reason": "EMAIL_IN_BLOCKLIST" }, "fee": 0 } ], "warnings": [ { "feature": "EMAIL", "risk": "EMAIL_IN_BLOCKLIST", "additional_data": { "blocklisted_session_id": null, "blocklisted_session_number": null, "api_service": null }, "log_type": "error", "short_description": "Email in blocklist", "long_description": "The system detected that the email is in the blocklist, which is not allowed.", "node_id": "feature_email_1" }, { "feature": "EMAIL", "risk": "DISPOSABLE_EMAIL_DETECTED", "additional_data": null, "log_type": "information", "short_description": "Disposable email detected", "long_description": "The system detected that the email is disposable, which is not allowed.", "node_id": "feature_email_1" } ], "matches": [ { "session_id": null, "session_number": null, "vendor_data": null, "verification_date": null, "email": "user@mailinator.com", "status": null, "is_blocklisted": true, "api_service": null, "source": "list_entry" } ] } ``` ## ذات صلة * [نظرة عامة على التحقق من البريد الإلكتروني](https://docs.didit.me/ar/core-technology/email-verification/overview.md) — سلوك الميزة والأسعار. * [تحذيرات التحقق من البريد الإلكتروني](https://docs.didit.me/ar/core-technology/email-verification/warnings-email-verification.md) — جميع رموز المخاطر، ومُشغِّلات الرفض والإجراءات القابلة للتكوين. * [نماذج البيانات — التحقق من البريد الإلكتروني](https://docs.didit.me/ar/reference/data-models.md#التحقق-من-البريد-الإلكتروني) — المخطط المرجعي حقلاً بحقل. * [API البريد الإلكتروني — إرسال OTP](https://docs.didit.me/ar/standalone-apis/email-send.md) و[التحقق من OTP](https://docs.didit.me/ar/standalone-apis/email-check.md) — endpoint مستقلة من خادم إلى خادم. * [Management API — القوائم](https://docs.didit.me/ar/management-api/lists/overview.md) — إدارة قائمة حظر البريد الإلكتروني التي تغذي `matches[]` بـ `source: list_entry`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.