واجهة API لمخاطر البريد الإلكتروني: التسليم والتسريب

curl

curl -X POST https://verification.didit.me/v3/email/risk/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alice@example.com",
    "country_code": "US",
    "vendor_data": "lead-123",
    "metadata": {"source": "signup_prescreen"}
  }'

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Email.AssessRisk(ctx, didit.EmailRiskRequest{
	Email: "alice@example.com",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.EmailRiskRequest;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.email().assessRisk(EmailRiskRequest.builder()
        .email("alice@example.com")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->email->assessRisk([
    'email' => 'alice@example.com',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Email.AssessRiskAsync(new EmailRiskRequest
{
    Email = "alice@example.com",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "82397be9-5921-4970-a979-2d5b43e08b33",
  "status": "Approved",
  "email": {
    "status": "Approved",
    "email": "alice@example.com",
    "is_breached": false,
    "breaches": [],
    "is_disposable": false,
    "is_undeliverable": false,
    "verification_attempts": 0,
    "verified_at": null,
    "warnings": [],
    "lifecycle": [],
    "matches": [],
    "email_intelligence": {
      "score": 4,
      "deliverable": "high",
      "breach_risk_level": "Low",
      "breach_risk_index": 4,
      "is_recent_breach": false,
      "is_frequent_breached": false,
      "is_disposable": false,
      "is_free_domain": false,
      "is_breached": false,
      "no_of_breaches": 0,
      "reason_codes": []
    },
    "enrichment": {
      "score": 4,
      "deliverable": "high",
      "breach_risk_level": "Low",
      "breach_risk_index": 4,
      "is_recent_breach": false,
      "is_frequent_breached": false,
      "is_disposable": false,
      "is_free_domain": false,
      "is_breached": false,
      "no_of_breaches": 0,
      "reason_codes": []
    }
  },
  "vendor_data": "lead-123",
  "metadata": {
    "source": "signup_prescreen"
  },
  "created_at": "2026-09-01T10:30:00.123456+00:00"
}

POST

risk

curl

curl -X POST https://verification.didit.me/v3/email/risk/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alice@example.com",
    "country_code": "US",
    "vendor_data": "lead-123",
    "metadata": {"source": "signup_prescreen"}
  }'

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Email.AssessRisk(ctx, didit.EmailRiskRequest{
	Email: "alice@example.com",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.EmailRiskRequest;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.email().assessRisk(EmailRiskRequest.builder()
        .email("alice@example.com")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->email->assessRisk([
    'email' => 'alice@example.com',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Email.AssessRiskAsync(new EmailRiskRequest
{
    Email = "alice@example.com",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "82397be9-5921-4970-a979-2d5b43e08b33",
  "status": "Approved",
  "email": {
    "status": "Approved",
    "email": "alice@example.com",
    "is_breached": false,
    "breaches": [],
    "is_disposable": false,
    "is_undeliverable": false,
    "verification_attempts": 0,
    "verified_at": null,
    "warnings": [],
    "lifecycle": [],
    "matches": [],
    "email_intelligence": {
      "score": 4,
      "deliverable": "high",
      "breach_risk_level": "Low",
      "breach_risk_index": 4,
      "is_recent_breach": false,
      "is_frequent_breached": false,
      "is_disposable": false,
      "is_free_domain": false,
      "is_breached": false,
      "no_of_breaches": 0,
      "reason_codes": []
    },
    "enrichment": {
      "score": 4,
      "deliverable": "high",
      "breach_risk_level": "Low",
      "breach_risk_index": 4,
      "is_recent_breach": false,
      "is_frequent_breached": false,
      "is_disposable": false,
      "is_free_domain": false,
      "is_breached": false,
      "no_of_breaches": 0,
      "reason_codes": []
    }
  },
  "vendor_data": "lead-123",
  "metadata": {
    "source": "signup_prescreen"
  },
  "created_at": "2026-09-01T10:30:00.123456+00:00"
}

استخدم POST /v3/email/risk/ عندما تحتاج إلى معلومات استخبارية عن البريد الإلكتروني دون أن تطلب من المستخدم إدخال رمز لمرة واحدة. لا يرسل هذا الطلب أي بريد إلكتروني. بل ينشئ جلسة API، ويثري العنوان، ويطبّق قواعد المخاطر الخاصة بالبريد الإلكتروني لديك، ثم يعيد الكتلة الموحّدة نفسها للبريد الإلكتروني التي يستخدمها التحقق من البريد الإلكتروني، وذلك في استجابة متزامنة واحدة. عند حفظ الطلب، يمكن لـ Didit أيضاً استخدام البريد الإلكتروني المُقيَّم كدليل مجمّع في الشبكات. قد تعرض مخططات الشبكات معلومات استخبارية عالية المخاطر عن البريد الإلكتروني، وسياق التسريبات، وتغطية الملفات الشخصية على وسائل التواصل الاجتماعي للإشارات المشتركة الخاصة بالبريد الإلكتروني، لكنها لا تكشف عنوان البريد الإلكتروني الخام لمؤسسات أخرى.

تفسير الاستجابة

status هو القرار النهائي لجلسة API هذه. وعادةً ما تكون قيمته Approved، لكن تقييم المخاطر قد ينتج In Review أو Declined.
email.is_breached وemail.is_disposable وemail.is_undeliverable إشارات ثابتة بنعم أو لا، تستخدمها في منطق التطبيق.
email.breaches يسرد أحدث التسريبات المعروفة التي يرد فيها العنوان، عند توفر التغطية، مع تاريخ التسريب وفئات البيانات المكشوفة.
email.email_intelligence.score يستخدم مقياساً للمخاطر من 0 إلى 100، حيث يعني الرقم الأعلى مخاطر أعلى. أما breach_risk_level (Low وMedium وHigh) وno_of_breaches فهما عرضان مشتقان.
email.email_intelligence.reason_codes يوضح الإشارات المُوحّدة التي أسهمت في النتيجة. وقد تزداد هذه الرموز مع الوقت، لذلك لا ترفض الرموز غير المعروفة.
email.email_intelligence وemail.enrichment اسمان بديلان للتوافق يشيران إلى الكائن الموحّد نفسه. ويمكن للتكاملات الجديدة قراءة email.enrichment.
email.matches يسرد جلسات أخرى في تطبيقك استُخدم فيها العنوان نفسه من مستخدم مختلف. استخدمه لاكتشاف الحسابات المكررة.
request_id هو معرّف جلسة API. احفظه مع vendor_data إذا كنت تحتاج إلى ربط النتيجة بعمليات webhook لاحقة أو بنشاط لوحة التحكم.

email.email_intelligence وemail.enrichment حقلان تُوفَّر بياناتهما على أساس أفضل جهد. قد يغيب كلاهما عند اكتمال الاستعلام، إذا لم تُرجَع بيانات استخبارية قابلة للاستخدام لذلك العنوان أو النطاق أو الخطة. ابنِ القواعد أولاً على is_breached وis_disposable وis_undeliverable، وتعامل مع غياب المعلومات الاستخبارية على أنه “غير معروف” وليس “آمن”.

الإضافة الخاصة بالبصمة الاجتماعية

اضبط enable_social على true لإضافة كتلة email_social إلى الاستجابة ضمن email. تتضمن هذه الكتلة المنصات الإلكترونية المسجّل عليها عنوان البريد الإلكتروني، مجمّعةً حسب الفئة، مع الإحصاءات الموجزة وأي تفاصيل للملفات الشخصية يعيدها شركاؤنا في البيانات.

email.email_social.profiles_registered وemail.email_social.profiles_checked هما الرقمان الرئيسيان: عدد المنصات التي أُكّد فيها تسجيل عنوان البريد الإلكتروني، من بين المنصات التي جرى تقييمها.
email.email_social.registered_platforms وemail.email_social.not_registered_platforms يسردان كل منصة مع category وscope (global، أو local للمنصات الخاصة بمنطقة معينة).
email.email_social.categories يعرض عدد التسجيلات ونسبتها لكل فئة، وemail.email_social.profiles يتضمن تفاصيل الملف الشخصي لكل منصة عندما تكشفها المنصة (الاسم، وعنوان الصورة، ونص النبذة، وحالة الخصوصية، وعلامة الحساب التجاري).
المؤشرات الملخّصة (digital_footprint_diversity وdigital_sophistication_index وengagement_depth_index وsubscription_affordability_index) مركّبات من 0 إلى 10. وقد يكون أي عدد من الأعداد null إذا لم يُرجع الفحص بيانات لها.

القيمة profiles_registered: 0 إجابة حقيقية، وليست فشلاً: فقد جرى فحص المنصات ولم يُعثر على عنوان البريد الإلكتروني في أي منها، وهذه إشارة شائعة إلى هوية مصطنعة. لا يتخذ هذا endpoint أي إجراء بشأنها بمفرده، لذلك استخدم email_no_social_presence_action في سير العمل لتحويلها إلى قرار مراجعة أو رفض. تغيب الكتلة عندما لا يكون enable_social مضبوطاً، وكذلك عندما يتعذر إكمال فحص وسائل التواصل الاجتماعي، وفي هذه الحالة لا تُحتسب رسوم الفحص.

سلوك البيئة التجريبية

تتحقق مفاتيح البيئة التجريبية من الطلب، وتعيد بيانات مقبولة ثابتة وقابلة للتكرار. ولا ترسل أي بريد إلكتروني، ولا تستهلك أرصدة، ولا تنشئ جلسة، ولا تسهم في الشبكات. وعند ضبط enable_social، تعيد هذه المفاتيح أيضاً كتلة email_social حتمية.

الفوترة

تكلّف استدعاءات Email Risk API مبلغ $0.04 بالسعر المعلن، وهو أقل مما ستكلفه عملية التحقق الكاملة من البريد الإلكتروني، لأنه لا يُرسل أي بريد إلكتروني. يصبح الطلب الفعلي قابلاً للفوترة بمجرد بدء الاستعلام، حتى إذا لم تتوفر بعض الحقول بأفضل جهد. تُفوتر إضافة البصمة الاجتماعية بشكل منفصل: وحدة email_social واحدة لكل طلب، تُضاف إلى سعر Email Risk API، متى اكتمل الفحص. ويغطي فحص الرصيد الذي يسبق الاستعلام الأمرين معاً.

التفويضات

x-api-key

string

header

مطلوب

مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys.

الجسم

application/json

string<email>

مطلوب

عنوان البريد الإلكتروني المراد احتساب درجة له.

مثال:

"alice@example.com"

country_code

string

تلميح دولة اختياري وفق معيار ISO 3166-1 alpha-2 أو alpha-3 لتغطية البيانات الاستخباراتية.

Maximum string length: 3

مثال:

"US"

signals

object

سياق اختياري للجهاز والشبكة يرصده تطبيقك. جميع الحقول اختيارية. يغذي تمريرها ميزة كشف التطابق عبر الجلسات في Networks.

Show child attributes

vendor_data

string

مرجعك الثابت لهذا الطلب. يتم تخزينه في جلسة API وإعادته في الاستجابة.

metadata

object | null

البيانات الوصفية بتنسيق JSON غير الحساسة الخاصة بك. يتم تخزينها في جلسة API وإعادتها في الاستجابة.

عند التعيين على true، يتم أيضاً البحث عن الأثر الرقمي الاجتماعي للعنوان - منصات البريد الإلكتروني والمنصات الاجتماعية والمهنية والتجارة الإلكترونية والترفيه المسجل عليها. يُفوتر كوحدة email_social واحدة لكل طلب بالإضافة إلى سعر هذا الـ endpoint نفسه.

مثال:

true

الاستجابة

اكتمل تقييم المخاطر. افحص status لمعرفة القرار؛ رمز HTTP دائماً ما يكون 200 لعمليات البحث المكتملة.

request_id

string<uuid>

مطلوب

معرّف جلسة API التي تم إنشاؤها لهذا الطلب. احفظه مع vendor_data إذا كنت بحاجة إلى ربط النتيجة بـ webhooks اللاحقة أو نشاط لوحة التحكم.

status

enum<string>

مطلوب

القرار النهائي لجلسة API هذه. عادةً ما يكون Approved؛ يمكن أن ينتج عن تقييم المخاطر In Review أو Declined.

الخيارات المتاحة:

Approved,

In Review,

Declined

created_at

string<date-time>

مطلوب

الطابع الزمني لهذه الاستجابة.

vendor_data

string | null

نسخة مطابقة من vendor_data التي أرسلتها، وتكون null عند عدم إرسال أي منها.

metadata

object | null

نسخة مطابقة من metadata التي أرسلتها، وتكون null عند عدم إرسال أي منها.

object

تقرير البريد الإلكتروني المعياري، وهو نفس الكتلة المستخدمة في استجابات التحقق من البريد الإلكتروني.

Show child attributes

آخر تعديل في ٧ نوفمبر ٢٠٢٦

​تفسير الاستجابة

​الإضافة الخاصة بالبصمة الاجتماعية

​سلوك البيئة التجريبية

​الفوترة

التفويضات

الجسم

الاستجابة

تفسير الاستجابة

الإضافة الخاصة بالبصمة الاجتماعية

سلوك البيئة التجريبية

الفوترة