التحقق المجمّع من البريد الإلكتروني عبر API: سير عمل عملي لمهام الدُفعات

التحقق المجمّع من البريد الإلكتروني عبر API: سير عمل عملي لمهام الدُفعات

السؤال: لديك قائمة كبيرة من العناوين في نظامك الخاص. كيف ترسلها عبر API الخاصة بـFairValid على دفعات، وتتعامل مع الأخطاء بأمان، وتقرأ النتائج دون أن تفقد تتبّع الأرصدة؟

الإجابة المختصرة: ابدأ في بيئة الاختبار باستخدام مفتاح اختبار. ثم قسّم القائمة إلى مهام تضم ما يصل إلى 5,000 عنوان، وامنح كل مهمة مفتاح عدم تكرار خاصًا بها. أرسل كل مهمة باستخدام مفتاح إنتاج، وتحقق من حالتها، وتصفّح النتائج حسب الحصيلة. تعامل مع عمليات التحقق المعلّقة والأعطال التقنية والنتائج «غير معروف» على أنها ثلاث حالات منفصلة.

جرى التحقق من الأدلة بتاريخ 13 نوفمبر 2026، استنادًا إلى مرجع API ودليل النتائج وقواعد الأرصدة لدى FairValid.

الخطوة 1: ابنِ تكاملك على بيئة الاختبار أولًا

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

تُرجع مهام الاختبار حالات حتمية: مكتملة أو معلّقة أو فاشلة أو ملغاة. راجع مرجع API لمعرفة عناوين بيئة الاختبار الدقيقة، واستخدمها للتأكد من أن شيفرتك تتعامل مع هذه الحالات. لا تُظهر هذه الحالات سوى النتائج التي صُممت لها. ولا تغطي كل مسار في تكاملك، لذا راجع مسارات الأخطاء الخاصة بك بشكل منفصل.

الخطوة 2: انتقل إلى مفتاح إنتاج بالصلاحيات المناسبة

للاستخدام الإنتاجي، ينص مرجع API على أنك تحتاج إلى مفتاح إنتاج بصلاحية submit لإنشاء المهام. أضف صلاحية read لقراءة حالة المهام ونتائجها. ويمكن أن تحمل مفاتيح الإنتاج أيضًا صلاحية balance. لا تظهر الأسرار الكاملة للمفاتيح إلا مرة واحدة، لذا خزّنها بأمان على خادمك عند إنشائها. ويوقف المفتاح الملغى الطلبات الجديدة.

تستخدم مهام الإنتاج قائمة انتظار التحقق ورصيد الأرصدة في مساحة عملك. وتظل صلاحيات المفاتيح وحدود إنفاقها وصلاحيات الوصول إلى مساحة العمل وحدود المعالجة سارية. فمفتاح الإنتاج لا يمنحك وصولًا غير محدود.

الخطوة 3: قسّم القائمة وأرسل المهام

تقبل كل مهمة من 1 إلى 5,000 عنوان بتنسيق JSON، بحجم يصل إلى 2 ميبيبايت. إليك نهجًا عمليًا:

1. قسّم قائمتك إلى أجزاء. على سبيل المثال، ستصبح 12,000 عنوان ثلاث مهام من 5,000 و5,000 و2,000.
2. امنح كل جزء مفتاح Idempotency-Key ثابتًا خاصًا به، وسجّل أيّ صفوفك دخل في أيّ جزء. إن الاحتفاظ بهذا الربط لديك يسهّل مطابقة النتائج مع سجلاتك.
3. أرسل إلى نقطة نهاية المهام. تُرجع المهمة الجديدة HTTP 202 مع معرّف job_id بصيغة UUID. وتُرجع إعادة المحاولة المطابقة HTTP 200 مع المهمة نفسها. أي إنه يمكنك إعادة إرسال الطلب نفسه بالمفتاح نفسه بعد انتهاء المهلة واستعادة المهمة الموجودة.

الخطوة 4: تعامل مع الخطأين المتشابهين

يمكن لكلتا الاستجابتين أن تمنعا الإرسال، لكنهما تعنيان أمرين مختلفين:

• قد تُرجَع HTTP 503 live_verification_unavailable أثناء توقف تشغيلي. ووفقًا لـمرجع API، يحدث ذلك دون حجز أي أرصدة. أعد المحاولة لاحقًا باستخدام مفتاح Idempotency-Key نفسه.
• تعني HTTP 402 key_cap_reached أن الطلب الجديد سيتجاوز حد الإنفاق الإجمالي للمفتاح طوال مدة صلاحيته. ويحتسب هذا الحد الأرصدة المخصومة بالفعل إضافةً إلى الأرصدة المحجوزة للهويات الفريدة المقبولة. لا تُنشأ أي مهمة ولا أي حجز. ولا يتجدد الحد الإجمالي بمرور الوقت، لذا لن يحل الانتظار المشكلة. راجع حد المفتاح في إعدادات مفاتيح API، أو استخدم مفتاحًا يتبقى له حد كافٍ للعمل. كما أن حد المفتاح لا يضيف أرصدة إلى مساحة العمل، بل يقيّد فقط ما يمكن لذلك المفتاح إنفاقه.

سجّل هاتين الاستجابتين بمعزل عن أخطاء الأذونات وحدود المعالجة، حتى يتلقى الشخص المناسب التنبيه المناسب.

الخطوة 5: تتبّع حالة المهمة، ثم تصفّح النتائج

تُرجع نقطة نهاية المهمة الحالة الراهنة للمهمة وملخصها. ويمكن أن تكون حالة المهمة: في قائمة الانتظار، أو قيد التشغيل، أو متوقفة مؤقتًا، أو قيد الإلغاء، أو ملغاة، أو مكتملة. وإذا طلبت الإلغاء، فقد يكتمل العمل الجاري بالفعل.

تُرجع نقطة نهاية النتائج ما يصل إلى 50 نتيجة في كل مرة، مع قيمة next_cursor موقّعة. مرّر هذه القيمة بوصفها معامل الاستعلام cursor. وهي تحتفظ بعامل التصفية والبحث الأصليين. وعوامل التصفية هي all وvalid وinvalid وcatch_all وunknown وstill_checking وnot_checked. ويمكنك استخدامها لجلب الصفوف التي تحتاج إلى قرار فقط، مثل كل ما صُنّف على أنه غير معروف.

الخطوة 6: حوّل النتائج إلى قرارات

يصف دليل النتائج النتائج بأنها أدلة، لا ضمان للتسليم:

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

الأعطال التقنية والعناصر غير المعالجة فئة منفصلة. وتنص قواعد الأرصدة لدى FairValid على أنها لا يُعاد تصنيفها على أنها غير معروف.

الخطوة 7: افهم حجوزات الأرصدة

ينص مرجع API على أن أرصدة مساحة العمل تُحجز عند قبول عمليات التحقق للمعالجة. وتخضع النتائج لقواعد الخصم والإرجاع نفسها المطبقة في لوحة التحكم. وبموجب قواعد الأرصدة، تكلّف النتيجة المكتملة «صالح» أو «غير صالح» رصيدًا واحدًا. أما نتائج «غير معروف» و«يقبل الكل» غير المحسومة فلا يُخصم عنها في النهاية أي رصيد تحقق، لأن الأرصدة المحجوزة تُحرَّر أو تُعاد. والحالة المعلّقة ليست نتيجة نهائية. كذلك لا يُخصم في النهاية أي رصيد عن الأعطال التقنية والعمل غير المعالج. وتحتفظ الأرصدة المُعادة بقواعد الدفعة وانتهاء الصلاحية التي كانت لها في الأصل.

تُبلغ نقطة نهاية الرصيد عن الأرصدة المتاحة والمحجوزة لمساحة عمل الإنتاج. وعندما تكون قيمة الحقل free_allowance_held صحيحة، تكون الحصة المجانية معلّقة ولا تُحتسب في available_credits أو free_available. وتظل الأرصدة المدفوعة متاحة. يحصل الحساب الأصلي على 300 رصيد مجاني كل شهر في تاريخ تسجيله، ولا تُرحَّل الأرصدة المجانية غير المستخدمة. ولا تحصل مساحات العمل الإضافية على حصة مجانية إضافية. تُستخدم الأرصدة المجانية أولًا، ولا تنتهي صلاحية الأرصدة المدفوعة ما دام الحساب مفتوحًا.

قائمة تحقق بسيطة

• اختبر باستخدام مفتاح اختبار وحالات بيئة الاختبار الموثقة.
• استخدم مفتاح إنتاج بصلاحيتي submit وread، وحدًّا يناسب العمل المخطط له.
• اجعل كل جزء 5,000 عنوان أو أقل، مع مفتاح عدم تكرار ثابت لكل جزء.
• أعد المحاولة بعد 503 لاحقًا بالمفتاح نفسه. ولا تنتظر زوال 402؛ بل عالج مسألة الحد.
• تصفّح النتائج باستخدام المؤشر الموقّع، مع التصفية حسب الحصيلة.
• افصل بين الحالات المعلّقة والأعطال التقنية و«غير معروف» في بياناتك.

إذا أردت تجربة سير العمل هذا، يمكنك إنشاء مفتاح اختبار وتشغيل مهمة في بيئة الاختبار دون استهلاك أرصدة قبل أول إرسال فعلي. ويتضمن مرجع API التفاصيل الكاملة لنقاط النهاية.