> ## 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 > أرسل رمز تحقق لمرة واحدة عبر POST /v3/email/send/ مع Didit: إعادة محاولة تلقائية عند فشل التسليم، صلاحية 5 دقائق، ودفع حسب الاستخدام بلا حد أدنى. ## OpenAPI ````yaml ar/openapi-25.json POST /v3/email/send/ 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/email/send/: post: tags: - Standalone APIs summary: إرسال رمز عبر البريد الإلكتروني description: >- أرسل رمزاً لمرة واحدة (OTP) إلى عنوان بريد إلكتروني، ثم تحقق منه باستخدام [`POST /v3/email/check/`](/ar/standalone-apis/email-check). **كيف يقترن الإرسال بالتحقق.** ترتبط حالة التحقق بتطبيقك مضافاً إليه عنوان `email` — لا يتطلب استدعاء التحقق المعامل `request_id`. يُنشئ كل إرسال جديد عملية تحقق معلقة تظل صالحة لمدة **5 دقائق**: استدعِ عملية التحقق باستخدام نفس العنوان والرمز الذي استلمه المستخدم قبل إغلاق هذه النافذة الزمنية. يؤدي استدعاء الإرسال مرة أخرى لنفس العنوان أثناء وجود عملية تحقق معلقة إلى إنشاء رمز جديد لنفس عملية التحقق (`status: "Retry"`، ونفس `request_id`)؛ ويتوقف الرمز السابق عن العمل. يتم إرفاق إعادة محاولة واحدة فقط كحد أقصى بهذه الطريقة (عمليتا إرسال في المجموع)؛ وأي إرسال إضافي يبدأ عملية تحقق جديدة تماماً بمعرّف `request_id` جديد. تُحسب نافذة الـ 5 دقائق بدءاً من أول عملية إرسال ولا يتم تمديدها بواسطة إعادات المحاولة. **الفحص المسبق لقابلية التسليم.** قبل إرسال أي شيء، يخضع العنوان للتحقق من بنيته النحوية والتحقق من سجلات DNS/MX. تُرجع العناوين التي لا يمكنها استلام الرسائل الرمز `200` مع `status: "Undeliverable"` و`reason: "email_can_not_be_delivered"` — ولا يتم إرسال أي بريد إلكتروني، ولا تتم فوترة أي شيء، ويتم إنهاء عملية التحقق على الفور بحالة `Declined` (يُرجع فحص المتابعة `Expired or Not Found`). يؤدي الإرسال الذي يفشل لسبب لا يتعلق بالعنوان (تعذر تسليم البريد الإلكتروني لمرحلة الإرسال) إلى إرجاع الرمز `503` بدلاً من ذلك: ولا يتم إرسال أي رمز، ولا تتم فوترة أي شيء، وتظل عملية التحقق مفتوحة ويمكن تكرار نفس الطلب. **تنسيق الرمز والعلامة التجارية.** تتكون الرموز من 4 إلى 8 خانات (`options.code_size`، والافتراضي 6)، وهي رقمية بشكل افتراضي؛ اضبط `options.alphanumeric_code: true` لاستخدام أحرف كبيرة وأرقام (مقارنة التحقق غير حساسة لحالة الأحرف). يتم توطين قالب البريد الإلكتروني عبر `options.locale` (54 لغة مدعومة) ويمكنه استخدام العلامة التجارية لتطبيقك عبر خيار العلامة البيضاء `options.use_white_label_customization`. **الفوترة.** رصيد API واحد للتحقق من البريد الإلكتروني لكل عملية إرسال ناجحة (`status: "Success"`)، ويتم خصمه في وقت الإرسال. عمليات الإرسال ذات الحالة `Retry` و`Undeliverable` مجانية، وعمليات الفحص مجانية أيضاً. **استمرار الجلسة.** يتم حفظ كل عملية تحقق جديدة كجلسة من نوع API: يمثل `request_id` معرّف جلسة حقيقياً يمكنك تمريره إلى `GET /v3/session/{sessionId}/decision/`، وتظهر عملية التحقق في Business Console، وتنطلق أحداث webhook الخاصة بـ `status.updated` أثناء تقدمها. **البيئة التجريبية.** تتخطى مفاتيح API الخاصة بالبيئة التجريبية مرحلتي التسليم والفوترة: بعد التحقق من صحة الطلب (لا يزال الإدخال المشوّه يُرجع الرمز `400`)، يُرجع endpoint الـ payload الثابت `Success` مع معرّف `request_id` عشوائي؛ ولا يتم إرسال أي بريد إلكتروني ولا يتم حفظ أي شيء. استخدم الرمز `123456` في فحص البيئة التجريبية. **المصادقة.** أرسل مفتاح API الخاص بتطبيقك في الرأس `x-api-key`. تُرجع بيانات الاعتماد المفقودة أو غير الصالحة الرمز `403` (`{"detail": "You do not have permission to perform this action."}`) — لا يُرجع هذا الـ API أبداً الرمز `401`. **حد المعدل.** ميزانية كتابة مشتركة تبلغ 300 طلب/دقيقة لكل مفتاح API عبر جميع endpoints الخاصة بـ POST/PATCH/DELETE؛ وتجاوزها يُرجع `429`. operationId: post_v3email_send requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email description: >- عنوان البريد الإلكتروني للمستلم. تُرجع العناوين المشوهة غير الصالحة `400`؛ أما العناوين الصالحة لغوياً ولكنها لا تستطيع تلقي البريد (فشل التحقق من DNS/MX) فتُرجع `200` مع `status: "Undeliverable"`. example: alice@example.com options: type: object description: >- تنسيق رمز لمرة واحدة، والتوطين، وخيارات العلامة التجارية. جميع الحقول اختيارية. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: >- عدد الأحرف في رمز OTP (أرقام افتراضياً؛ أحرف كبيرة وأرقام عندما يكون `alphanumeric_code` مضبوطاً على `true`). alphanumeric_code: type: boolean default: false description: >- عندما تكون `true`، يتكون OTP من أحرف كبيرة `A–Z` وأرقام `0–9` بدلاً من الأرقام فقط. لا تتأثر مقارنة `/v3/email/check/` بحالة الأحرف. locale: type: string maxLength: 5 enum: - en - ar - bn - bg - bs - ca - cs - da - de - el - es - et - fa - fi - fr - he - hi - hr - hu - hy - id - it - ja - ka - kk - ko - ky - lt - lv - cnr - mk - mn - ms - nl - 'no' - pl - pt-BR - pt - ro - ru - sk - sl - so - sq - sr - sv - th - tr - uk - uz - vi - zh-CN - zh-TW - zh description: >- لغة قالب البريد الإلكتروني لرمز OTP. القيمة الافتراضية هي `en`. تُرجع القيم غير المدعومة الخطأ `400` مع سرد لجميع اللغات المدعومة. example: en use_white_label_customization: type: boolean default: false description: >- عندما تكون `true`، يستخدم بريد OTP الإلكتروني تخصيص العلامة البيضاء لتطبيقك (الشعار، والألوان، والعلامة التجارية للمرسل) بدلاً من قالب Didit الافتراضي. signals: type: object description: >- إشارات اختيارية للجهاز والشبكة حول المستخدم النهائي، تُمرَّر إلى طبقة مكافحة الاحتيال لتحسين اكتشاف حركة المرور المسيئة أو الآلية. جميع الحقول اختيارية. properties: ip: type: string description: عنوان IP لجهاز المستخدم النهائي. IPv4 أو IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- المعرّف الفريد لجهاز المستخدم النهائي. نظام Android: `ANDROID_ID`؛ نظام iOS: `identifierForVendor`. example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: منصة جهاز المستخدم النهائي. device_model: type: string maxLength: 255 description: طراز جهاز المستخدم النهائي. example: iPhone17,2 os_version: type: string maxLength: 64 description: إصدار نظام التشغيل لجهاز المستخدم النهائي. example: 18.0.1 app_version: type: string maxLength: 64 description: إصدار تطبيقك. example: 1.2.34 user_agent: type: string maxLength: 512 description: وكيل المستخدم لمتصفح المستخدم النهائي أو تطبيقه. example: >- Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1 vendor_data: type: string description: >- معرّف اختياري يتحكم فيه المتصل (معرّف المستخدم الداخلي لديك، أو بريد إلكتروني، أو UUID، وما إلى ذلك) يُحفظ في الجلسة ويُعاد في استجابة الإرسال، واستجابة فحص التطابق، وwebhook، وBusiness Console. استخدمه لربط `request_id` الخاص بـ Didit بسجل المستخدم لديك. metadata: type: object nullable: true description: >- كائن JSON اختياري حرّ التنسيق يُحفظ في الجلسة ويُعاد في استجابة الإرسال، واستجابة فحص المطابقة، وwebhooks، وBusiness Console. required: - email examples: Numeric 6-digit code: summary: افتراضي — رمز رقمي مكوّن من 6 أرقام باللغة الإنجليزية value: email: alice@example.com options: locale: en vendor_data: user-1234 Alphanumeric 8-character code: summary: أحرف كبيرة + أرقام، قالب إسباني value: email: bob@example.com options: code_size: 8 alphanumeric_code: true locale: es White-label branding: summary: >- أرسل البريد الإلكتروني الذي يحتوي على رمز OTP مع تخصيص العلامة البيضاء لتطبيقك value: email: carol@example.com options: locale: en use_white_label_customization: true vendor_data: user-5678 responses: '200': description: >- تم تأكيد استلام الإرسال. تحقق من `status`: تعني `Success` و`Retry` أن الرمز في طريقه للإرسال؛ بينما تعني `Undeliverable` أن العنوان لا يمكنه استلام البريد وأنه قد تم إنهاء التحقق مسبقاً بحالة `Declined`. تمثل `request_id` معرف الجلسة المحفوظ (نفس المعرف عند استخدام `Retry`). content: application/json: schema: $ref: '#/components/schemas/EmailVerificationSendResponse' examples: Success: summary: >- تم إرسال رمز لمرة واحدة عبر البريد الإلكتروني لعملية تحقق جديدة (تخضع للفوترة) value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- الإرسال الثاني خلال نافذة الـ 5 دقائق — رمز جديد، نفس request_id، مجاني value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Undeliverable: summary: >- فشل العنوان في التحقق من DNS/MX — تم إنهاء التحقق بالحالة مرفوضة، ولم تتم فوترة أي شيء value: request_id: cb1a5011-344d-444d-bdce-218904745d7f status: Undeliverable reason: email_can_not_be_delivered vendor_data: user-1234 metadata: null '400': description: >- خطأ في التحقق من الصحة — غلاف أخطاء الحقول الخاص بـ DRF: مصفوفة رسائل واحدة لكل حقل مخالف، متداخلة تحت `options` لأخطاء الخيارات. content: application/json: examples: Invalid email: summary: عنوان بريد إلكتروني غير صالح value: email: - Enter a valid email address. Unsupported locale: summary: '`options.locale` خارج المجموعة المدعومة' value: options: locale: - >- Invalid locale. Supported locales are en, ar, bn, bg, bs, ca, cs, da, de, el, es, et, fa, fi, fr, he, hi, hr, hu, hy, id, it, ja, ka, kk, ko, ky, lt, lv, cnr, mk, mn, ms, nl, no, pl, pt-BR, pt, ro, ru, sk, sl, so, sq, sr, sv, th, tr, uk, uz, vi, zh-CN, zh-TW, zh. Code size out of range: summary: '`options.code_size` خارج النطاق 4–8' value: options: code_size: - Ensure this value is less than or equal to 8. '403': description: >- تم رفض الإذن. يُرجع عند فقدان الرأس `x-api-key` (`{"detail": ...}`)؛ ويُرجع المفتاح الخاطئ أو الملغى أو منتهي الصلاحية `401`. يُرجع أيضاً قبل أي إرسال عندما لا يغطي رصيد المؤسسة رصيداً واحداً لـ API التحقق من البريد الإلكتروني (`{"error": ...}`). content: application/json: examples: Missing or invalid API key: summary: لا يوجد رأس `x-api-key`، أو أن المفتاح غير صالح/ملغى value: detail: You do not have permission to perform this action. Not enough credits: summary: رصيد المؤسسة لا يمكنه تغطية سعر الإرسال value: error: You don't have enough credits to perform this request. '429': description: >- تم تجاوز حد المعدل. تشترك نقاط endpoint الخاصة بـ POST/PATCH/DELETE في ميزانية قدرها 300 طلب كتابة في الدقيقة لكل مفتاح API (إنشاء المعاملات واستيعاب الأحداث لهما ميزانية منفصلة تبلغ 600). تتضمن الاستجابة رؤوس `X-RateLimit-Limit` و`X-RateLimit-Remaining` و`X-RateLimit-Reset` و`Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: أكثر من 300 طلب كتابة في الدقيقة الحالية value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': description: >- تعذر إرسال البريد الإلكتروني لسبب لا علاقة له بالعنوان (تعذر الوصول إلى مزود خدمة البريد الإلكتروني، أو انتهت مهلة الاتصال، أو رفض الإرسال نفسه)، لذلك لم يُرسل أي رمز ولم تتم فوترة أي شيء أو احتسابه كمحاولة إرسال. كرر الطلب نفسه. content: application/json: examples: Email delivery unavailable: summary: >- فشل مزود خدمة البريد الإلكتروني بعد إعادة محاولة تلقائية واحدة value: detail: >- Email delivery is temporarily unavailable. Please try again. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/email/send/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "email": "alice@example.com", "options": { "code_size": 6, "locale": "en" }, "vendor_data": "user-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.email.send_code( email="alice@example.com", options={ "locale": "en", }, vendor_data="user-1234", ) 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.email.sendCode({ email: "alice@example.com", options: { locale: "en", }, vendor_data: "user-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.SendCode(ctx, didit.EmailSendCodeParams{\n\tEmail: \"alice@example.com\",\n\tOptions: didit.Some(didit.EmailSendCodeParamsOptions{\n\t\tLocale: didit.Some(didit.EmailSendCodeParamsOptionsLocale(\"en\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\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.EmailSendCodeParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.email().sendCode(EmailSendCodeParams.builder() .email("alice@example.com") .options(EmailSendCodeParams.Options.builder() .locale(EmailSendCodeParams.Options.Locale.of("en")) .build()) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- email->sendCode([ 'email' => 'alice@example.com', 'options' => [ 'locale' => 'en', ], 'vendor_data' => 'user-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.email.send_code( email: "alice@example.com", options: { locale: "en", }, vendor_data: "user-1234" ) 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.Email.SendCodeAsync(new EmailSendCodeParams { Email = "alice@example.com", Options = new EmailSendCodeParamsOptions { Locale = new EmailSendCodeParamsOptionsLocale("en"), }, VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: EmailVerificationSendResponse: type: object properties: request_id: type: string format: uuid description: >- معرّف الجلسة لعملية التحقق. يُرجع إرسال `Retry` نفس قيمة `request_id` مثل الإرسال الأصلي. يظهر هذا المعرّف في Business Console، ويتم إرجاعه مرة أخرى بواسطة طلب `POST /v3/email/check/` مكتمل، ويمكن تمريره إلى `GET /v3/session/{sessionId}/decision/`. status: type: string enum: - Success - Retry - Undeliverable description: >- `Success` — تم إرسال OTP عبر البريد الإلكتروني لعملية تحقق جديدة (تتم فوترتها). `Retry` — تم إرسال OTP جديد عبر البريد الإلكتروني لعملية التحقق المعلقة التي تم إنشاؤها بواسطة إرسال سابق (مجانًا). `Undeliverable` — فشل العنوان في التحقق من إمكانية التسليم أو تعذر إرسال الرسالة؛ يتم إنهاء عملية التحقق فورًا كـ `Declined` ولا تتم فوترة أي شيء. reason: type: string nullable: true enum: - email_can_not_be_delivered - null description: >- `email_can_not_be_delivered` عندما تكون `status` هي `Undeliverable`؛ و`null` خلاف ذلك. vendor_data: type: string nullable: true description: نسخة مطابقة من `vendor_data` المخزنة في الجلسة (من الإرسال الأول). metadata: type: object nullable: true description: نسخة مطابقة من `metadata` المخزنة في الجلسة (من الإرسال الأول). 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.