فحص البريد الإلكتروني في الوقت الفعلي

POST/v1/realtime/check/email

افحص بشكل متزامن عنوان بريد إلكتروني واحد مقابل من منتج واحد إلى عشرة من منتجات البريد الإلكتروني في الوقت الفعلي. المحرّك وعقد الفوترة وشكل الاستجابة مطابقة لـ نقطة نهاية الهاتف؛ ولا تختلف إلا السلسلة وصيغة المعرّف.

المعاملات

الحقل	النوع	مطلوب	الوصف
identifier	string	نعم	عنوان بريد إلكتروني واحد، على سبيل المثال user@example.com.
country	string	لا	يجب حذفه مع البريد الإلكتروني. إرسال رمز بلد مع منتج بريد إلكتروني مرفوض.
product_ids	array<int>	نعم	مصفوفة من 1 إلى 10 معرّفات لمنتجات البريد الإلكتروني في الوقت الفعلي.

يجب أن يكون البلد فارغًا

لا يوجد بُعد للبلد في البريد الإلكتروني. country اختياري في نقطة نهاية الهاتف لكنه غير مقبول هنا — والطلب الذي يحمله يفشل في التحقق قبل إرسال أي شيء أو احتسابه.

مفتاح عدم التكرار مطلوب

يُشترط Idempotency-Key في كل طلب. إعادة المحاولة بالطلب نفسه وبالمفتاح نفسه لا تحتسب مرتين؛ أما تغيير الحمولة فيُرجع 409. راجع عدم التكرار وإعادة المحاولة.

اختيار المنتجات

منتجات البريد الإلكتروني والهاتف سلسلتان مختلفتان ولا يمكن جمعهما في طلب واحد. اقرأ id لمدخل تكون فيه mode مساوية لـ realtime وتكون سلسلته البريد الإلكتروني من منتجات الوقت الفعلي، المدعومة بـ GET /v1/products. تمرير المعرّف النصي لا ينجح هنا أبدًا، ومعرّف منتج هاتف في طلب بريد إلكتروني مرفوض باعتباره سلسلة غير قابلة للمطابقة.

مثال الاستجابة

{
  "request_id": "b7d2a1c4-9f3e-4a1b-8c5d-2e6f7a8b9c0d",
  "identifier": "user@example.com",
  "series": "email",
  "status": "succeeded",
  "request_status": "completed",
  "replayed": false,
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "results": [
    {
      "product_id": 49,
      "product": "insemailvalid-rt",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-13T10:00:00Z",
      "error_code": null
    }
  ]
}

قيم product_id أعلاه أمثلة — تأكّد من معرّفات منتجات البريد الإلكتروني الحالية في منتجات الوقت الفعلي قبل إرسال طلب حقيقي. وrequest_id هو UUID، وcached يوجد داخل كل نتيجة وليس في المستوى الأعلى.

مثال cURL

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/email" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"user@example.com","product_ids":[49]}'

أخطاء خاصة بالبريد الإلكتروني

HTTP	code	المعنى
400	invalid_realtime_request	العنوان مشوّه، أو أُرسل country، أو كانت المعرّفات تنتمي إلى سلسلة أخرى، أو لم يُقدَّم أي معرّف. لا يُرسل شيء ولا يُحتسب شيء.
400	idempotency_key_required	ترويسة Idempotency-Key مفقودة.
402	insufficient_balance	الرصيد لا يغطي الحجز؛ فلا يبدأ أي عنصر.
409	request_in_progress / idempotency_conflict	المفتاح نفسه ولا يزال قيد التنفيذ، أو المفتاح نفسه مع حمولة مختلفة.

أما رموز الحالة المتبقية — 401 و403 و429 و503 و500 — فتتصرّف تمامًا كما هو موثّق في نقطة نهاية الهاتف.