مرجع API للتحقق من البريد الإلكتروني

ابدأ الآن

أنشئ مفتاح اختبار في مفاتيح API، واحتفظ به على خادمك، واضبط FAIRVALID_API_KEY وFAIRVALID_BASE_URL. تعمل مفاتيح الاختبار مع العناوين المحجوزة @example.com. لا تُجري أي استدعاء لمزوّد الخدمة ولا تستهلك أي أرصدة.

curl -X POST "$FAIRVALID_BASE_URL/api/v1/jobs" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY" \
  -H "Idempotency-Key: my-import-2026-10-05" \
  -H "Content-Type: application/json" \
  -d '{"emails":["deliverable@example.com","pending@example.com"]}'

لبيئة الإنتاج، أنشئ مفتاح Live بنطاق submit واستخدم /api/v1/jobs أو /api/v1/verifications. وأضف نطاق read لقراءة حالة المهمة ونتائجها.

تعيد المهمة الجديدة HTTP 202 ومعرّف UUID job_id. وتعيد إعادة المحاولة المطابقة HTTP 200 مع المهمة نفسها. تتضمن الاستجابات version: v1 وbrand: FairValid وترويسات no-store.

المفاتيح وحدود الإنفاق

مرّر Authorization: Bearer fv_live_… أو Bearer fv_test_… من الخادم. تظهر الأسرار الكاملة مرة واحدة فقط. يمكن أن تمتلك المفاتيح المباشرة النطاقات submit وread وbalance. يتوقف المفتاح المُلغى عن قبول الطلبات الجديدة. وتصل مفاتيح الاختبار إلى مهامها المحاكاة الخاصة بها.

يشمل الحد الإجمالي مدى الحياة للمفتاح المباشر الأرصدةَ المحتسبة بالفعل والأرصدة المحجوزة للهويات الفريدة المقبولة. ولا يمكنه إضافة أرصدة إلى مساحة العمل. يعيد أي طلب جديد يتجاوز الحد HTTP 402 key_cap_reached دون إنشاء مهمة أو حجز. يؤدي خفض الحد إلى منع العمل الجديد؛ أما العمل المقبول فيستمر.

تستخدم المهام المباشرة قائمة انتظار التحقق ورصيد الأرصدة الخاصين بمساحة عملك. تظل نطاقات المفاتيح وحدودها والوصول إلى مساحة العمل وحدود المعالجة سارية. تُحجز أرصدة مساحة العمل عند قبول عمليات التحقق للمعالجة؛ وتخضع النتائج لقواعد الاحتساب والإرجاع نفسها المطبقة في لوحة التحكم.

أثناء الإيقاف التشغيلي المؤقت، قد يُعيد إرسال مباشر جديد HTTP 503 live_verification_unavailable دون حجز أي أرصدة. أعد المحاولة لاحقًا باستخدام Idempotency-Key نفسه.

المهام والنتائج

الطريقة	المسار	الغرض
`POST`	`/api/v1/jobs`	أرسل من 1 إلى 5,000 عنوان بتنسيق JSON، بحجم أقصاه 2 MiB.
`POST`	`/api/v1/verifications`	أرسل عنوانًا فعليًا واحدًا أو استخدم المحاكي الأصلي للعنوان الفردي.
`GET`	`/api/v1/jobs/{id}`	قراءة الحالة الحالية للمهمة وملخصها.
`GET`	`/api/v1/jobs/{id}/results`	قراءة ما يصل إلى 50 نتيجة ومؤشر تالٍ موقَّع.
`POST`	`/api/v1/jobs/{id}/cancel`	اطلب الإلغاء؛ قد تكتمل الأعمال الجارية.
`GET`	`/api/v1/balance`	قراءة الرصيد المتاح والمحجوز الحالي لمساحة العمل.

curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"
curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID/results" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"

مرّر next_cursor بوصفه معامل الاستعلام cursor، فهو يحمل عامل التصفية والبحث الأصليين. عوامل التصفية هي all وvalid وinvalid وcatch_all وunknown وstill_checking وnot_checked. تطابق حالات النتائج والرصيد المباشرة لقطة لوحة التحكم. يمكن أن تكون حالة المهمة: queued أو running أو paused أو canceling أو canceled أو completed. وتُرجع مهام الاختبار حالات حتمية: completed أو pending أو failed أو cancelled.

الأخطاء وإعادة المحاولة الآمنة

أرسل Idempotency-Key يتكون من 8 إلى 128 حرفًا من الحروف أو الأرقام أو النقاط أو النقطتين الرأسيتين أو الشرطات السفلية أو الواصلات المسموح بها، مع كل إرسال لمهمة وكل إرسال مباشر لعنوان واحد. أعد محاولة أي استجابة غير مؤكدة باستخدام مفتاح API نفسه ومفتاح عدم التكرار نفسه والمتن المُوحَّد نفسه. يقتصر نطاق الإعادة على مفتاح API؛ لذا قد يؤدي استبدال بيانات الاعتماد هذه وإعادة الإرسال إلى إنشاء عملية تشغيل أخرى. تؤدي إعادة استخدام مفتاح عدم التكرار مع متن مختلف إلى إرجاع HTTP 409 idempotency_conflict. لا تستخدم مفتاحًا جديدًا إلا إذا كنت تقصد عملية تشغيل جديدة قد يُخصم عنها رصيد.

يعني الرمز HTTP 401 أن المفتاح مفقود أو مُلغى أو يفتقر إلى النطاق المطلوب. ويشمل HTTP 422 العناوين غير الصالحة أو تجاوز حدود القائمة. تُرجع مهام الدُفعات التجريبية HTTP 429 بعد 20 مهمة جديدة لكل مساحة عمل في الساعة أو 100 مهمة خلال 30 يومًا؛ أما المحاولات المتطابقة فتُرجع المهمة الأصلية. ويعني HTTP 503 أن الطلب غير متاح مؤقتًا؛ ولا يُثبت ظهور 503 بعد إرسال غير مؤكد أن المهمة لم تُنشأ، لذا أعد المحاولة باستخدام مفتاح عدم التكرار (idempotency key) نفسه. تتضمن الأخطاء رمزًا ورسالة ومعرّف طلب.

بيئة اختبار مجانية

لا تقبل مفاتيح الاختبار إلا هذه العناوين: deliverable@example.com وundeliverable@example.com وrisky@example.com وunknown@example.com وpending@example.com وerror@example.com. وهي تحاكي النتائج: صالح، وغير صالح، وcatch-all، وغير معروف، ومعلّق، وغير متاح. وتدعم مهام الاختبار المجمّعة الحالة والنتائج والإلغاء وإعادة التشغيل دون المساس بالتحقق الفعلي أو سجل الأرصدة.

يُحتفظ بمهام الاختبار المجمّعة (sandbox) وسجلات إعادة تنفيذها لمدة 30 يومًا. بعد انقضاء هذه المدة، استخدم مفتاح عدم تكرار جديدًا لإجراء اختبار جديد.

يستخدم محاكي مفتاح الاختبار الأصلي /api/v1/verifications إصدار الاستجابة السابق 2026-10-01 وحقولًا بصيغة camelCase. استخدم /api/v1/jobs للمحاكي المجمّع ذي الإصدارات.

خطافات ويب (webhooks) موقّعة

يتولى دورا المالك والمدير تهيئة نقاط نهاية HTTPS لـ job.completed وjob.canceled. ويستخدم اختبار ping test.ping. تحتوي حمولات المهام على معرّف حدث ثابت ومعرّف المهمة والحالة وملخص خالٍ من العناوين وأعداد الرصيد المُحتسب والمُعاد ورابط النتائج. ولا تتضمن أبدًا عناوين بريد إلكتروني أو بيانات المزوّد.

اقرأ FairValid-Webhook-Id وFairValid-Webhook-Timestamp وFairValid-Webhook-Signature. التوقيع هو fv1= متبوعًا بقيمة HMAC-SHA256 بالنظام الست عشري وبأحرف صغيرة، محسوبة على البايتات الخام لـ fv1\n{event ID}\n{Unix timestamp}\nيليها مباشرةً نص JSON الخام. استخدم مقارنة ثابتة الزمن. ارفض الطوابع الزمنية التي تختلف عن ساعتك بأكثر من خمس دقائق، وأزل التكرارات حسب معرّف الحدث في تخزين دائم.

أعِد أي استجابة 2xx خلال 10 ثوانٍ. تُعاد محاولة عمليات التسليم الفاشلة أو غير المؤكدة حتى ثماني مرات بمعرّف الحدث نفسه؛ ويمكنك مراجعة سجل آخر 30 يومًا أو إعادة التسليم يدويًا. تُرفض عمليات إعادة التوجيه والوجهات الخاصة. تستخدم المحاولات الجديدة السر الجديد بعد تدويره. احتفظ بالسر السابق لمدة 24 ساعة للتحقق من توقيعات المحاولات الجارية.

أمثلة قابلة للتشغيل

يتضمن المستودع packages/contracts/examples/job.mjs وpackages/contracts/examples/webhook-receiver.mjs. شغّل مثال المهمة باستخدام Node 22 ومفتاح اختبار. يتحقق المستقبِل من البايتات الخام الدقيقة لنص الطلب، ومن السرّين الحالي والسابق أثناء التدوير. ضع HTTPS أمامه، واستبدل مجموعة معرّفات الأحداث المخزنة في الذاكرة بمخزن دائم وذري قبل الاستخدام في بيئة الإنتاج.

FAIRVALID_API_KEY=... FAIRVALID_BASE_URL=https://YOUR_FAIRVALID_HOST \
  node packages/contracts/examples/job.mjs