مرجع REST API لأداة Email Verifier

تتوفر API لأداة Email Verifier ضمن /api/v1. استخدم مضيف TrekMail الذي يستخدمه حسابك لتسجيل الدخول. تستخدم الأمثلة أدناه https://YOUR-TREKMAIL-HOST كقيمة نائبة.

المصادقة والنطاقات

مرر رمز API في ترويسة Authorization:

Authorization: Bearer YOUR_API_TOKEN

فعّل النطاقات عند إنشاء الرمز:

امنح العميل كلا النطاقين إذا كان يجب أن يرسل العمل ثم يقرأ النتيجة أو ينزلها.

المضيف وتنسيق الطلب

تستخدم كل الأمثلة أجسام طلب JSON ورمز Bearer. أداة رفع الملفات في لوحة التحكم منفصلة عن API: تقبل POST /verify/bulk مصفوفة JSON باسم emails، وليس ملف multipart. استخدم المضيف المطابق للحساب والرمز بالضبط. لا تفترض أن رمزًا أو رصيدًا من مضيف ذي علامة تجارية يعمل على مضيف آخر.

أرسل Content-Type: application/json مع طلبات POST /verify وPOST /verify/bulk. خزّن الرمز وقيمة منع التكرار خارج التعليمات البرمجية من جانب العميل.

منع التكرار

تتطلب POST /api/v1/verify/bulk وDELETE /api/v1/verify/bulk/{jobId} ترويسة Idempotency-Key. أنشئ قيمة جديدة لكل عملية مقصودة، ولا تعد استخدامها إلا عند إعادة محاولة العملية نفسها.

Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee

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

التعامل مع نتيجة شبكة غير مؤكدة

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

ملخص نقاط النهاية

أضف /api/v1 في بداية كل مسار في هذا الجدول.

قراءة رصيد التحقق

GET /api/v1/verify/credits

على مضيف TrekMail القياسي، تتضمن الاستجابة حصة الخطة والرصيد المشترى:

{
  "monthly_limit": 300,
  "monthly_used": 120,
  "monthly_remaining": 180,
  "purchased_balance": 5000,
  "total_available": 5180,
  "plan": "pro",
  "trialing": false,
  "resets_at": "2026-10-01T00:00:00+00:00"
}

على مضيف White Label، لا يتوفر للمنتج ذي العلامة التجارية سوى الرصيد المشترى، لذلك تحتوي الاستجابة على purchased_balance وtotal_available.

مثال للطلب:

curl https://YOUR-TREKMAIL-HOST/api/v1/verify/credits \
  -H "Authorization: Bearer YOUR_API_TOKEN"

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

حقول الرصيد

تحتوي استجابات رصيد White Label على حقول أقل عمدًا لأن المنتج ذي العلامة التجارية يستخدم الرصيد المشترى فقط.

التحقق من عنوان واحد

POST /api/v1/verify

{
  "email": "person@example.com",
  "mode": "quick"
}

تتضمن الاستجابة email وstatus وtrust_score وchecks وprovider وrisk_factors وcredits_remaining. على المضيف القياسي، تحتوي credits_remaining على قيمتَي monthly وpurchased. قد يختلف الشكل التفصيلي لـchecks حسب الوضع وما يتيحه موفر الاستقبال.

يكلف Quick رصيدًا واحدًا. يكلف Deep عادة رصيدين، بينما تُحسب الاستثناءات الخاصة بالموفر برصيد واحد. إذا تعذر تشغيل التحقق بعد الخصم، يعيد طلب العنوان الفردي ذلك الخصم ويرجع استجابة عدم توفر مؤقت.

مثال للطلب:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","mode":"quick"}'

استخدم status وtrust_score وprovider وrisk_factors ذات المستوى الأعلى كعقد التطبيق المعتاد. تتضمن checks أدلة مساندة مفيدة، لكن قد تختلف المفاتيح الفردية عند تخطي فحص سابق أو عدم توفره أو حصول Deep على معلومات إضافية.

تفسير النتيجة الفردية

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

إنشاء مهمة مجمعة

POST /api/v1/verify/bulk

{
  "emails": ["first@example.com", "second@example.net"],
  "name": "September contacts",
  "mode": "deep"
}

تُوحّد التكرارات قبل التسعير. تعيد المهمة الجديدة الناجحة 201 مع:

{
  "job_id": 42,
  "total": 2,
  "status": "pending",
  "rejected_count": 0,
  "rejected_sample": [],
  "credits_charged": 4,
  "breakdown": {"probe": 2, "skip": 0, "deep_savings": 0}
}

توضح probe وskip حساب سعر Deep. تمثل deep_savings الفرق عن تحصيل سعر Deep الكامل لكل عنوان مرسل. تعيد القائمة المكررة job_id والحالة الموجودين بدلًا من بدء مهمة أخرى.

مثال للطلب:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee" \
  -d '{"name":"September contacts","mode":"deep","emails":["first@example.com","second@example.net"]}'

تختبر API القيم المرسلة للتأكد من صحة بنية البريد قبل قبول المهمة. إذا رُفضت كل الإدخالات، تعيد 422 ولا تنشئ مهمة. إذا رُفض بعضها، تعرض الاستجابة الناجحة rejected_count وما يصل إلى خمس قيم في rejected_sample. لا تعتمد على تلك العينة الصغيرة كتقرير تنظيف كامل للبيانات، بل احتفظ بنتيجة التحقق من المصدر في أداة الاستيراد لديك.

قائمة تحقق للإرسال المجمع

1. اقرأ المصدر ووحّده في تطبيقك.
2. اجعل الطلب في حدود 50,000 إدخال مرسل.
3. أنشئ مفتاح منع التكرار وخزّنه قبل الطلب.
4. اختر اسمًا للمهمة يتيح للمشغّل التعرف عليها لاحقًا.
5. خزّن job_id وcredits_charged وتفصيل السعر الذي يعيده TrekMail.
6. استعلم دوريًا عن job_id المخزّن، ولا تستنتج الاكتمال من طلب HTTP الأصلي.

قراءة مهمة

GET /api/v1/verify/bulk/{jobId}

تتضمن الاستجابة الأساسية job_id وname وstatus وtotal وprocessed وprogress وsummary وcreated_at وcompleted_at.

عندما تتوفر نتائج لمهمة مكتملة أو جزئية أو فاشلة، تتضمن الاستجابة أيضًا:

{
  "results": [
    {
      "email": "person@example.com",
      "status": "valid",
      "trust_score": 82,
      "checks": {},
      "provider": "example.com",
      "risk_factors": ["no_dmarc"]
    }
  ],
  "pagination": {"page": 1, "per_page": 100, "total": 1, "last_page": 1}
}

معلمات الاستعلام الاختيارية:

يمكن تنزيل مهمة ملغاة تتضمن صفوفًا معالجة، لكن استخدم نقطة نهاية التنزيل لتصديرها.

قراءة حالات المهمة دون تخمين

ينبغي لعميل API الاستعلام دوريًا مع زيادة وقت الانتظار. لا ترسل مهمة مجمعة جديدة لمجرد أن المهمة الحالية ما زالت معلقة أو لأن مهلة طلب شبكة انتهت محليًا.

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

{
  "job_id": 42,
  "name": "September contacts",
  "status": "processing",
  "total": 1500,
  "processed": 400,
  "progress": 27,
  "summary": {"safe": 220, "valid": 105, "risky": 55, "invalid": 20},
  "created_at": "2026-09-04T13:15:00+00:00",
  "completed_at": null
}

يمكن أن تتسع summary مع اكتمال العمل. استخدم processed وtotal لعرض التقدم بدلًا من جمع الفئات التي يتعرف عليها تطبيقك حاليًا فقط.

تنزيل مهمة

GET /api/v1/verify/bulk/{jobId}/download

يتوفر التنزيل للمهام المكتملة أو الجزئية أو الملغاة التي تتضمن صفوفًا معالجة. وهو يبث CSV بأعمدة Email وStatus وTrust Score وProvider وRisk Factors.

مثال:

curl -o september-results.csv \
  "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/download?filter=safe_risky" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

احفظ الملف المنزّل خلال مدة الاحتفاظ بالنتائج البالغة 15 يومًا. CSV ملف تصدير لمسار عملك، ولا يغيّر الموافقة أو الاشتراكات أو سجلات جهات الاتصال في نظام آخر.

تعيد نقطة نهاية التنزيل تعارضًا عندما لا يتوفر تصدير معالج. افحص حالة المهمة أولًا. يبث الطلب الناجح CSV بدلًا من إعادته داخل JSON، لذا تعامل معه كاستجابة ملف في عميل HTTP.

عرض قائمة المهام

GET /api/v1/verify/bulk

استخدم page وper_page وstatus الاختيارية. القيمة الافتراضية لـper_page هي 20 وتقبل من 1 إلى 100. حالات المهمة هي pending وprocessing وcompleted وpartial وcancelled وfailed.

تحتوي الاستجابة على مصفوفة jobs وكائن pagination. يتضمن كل سجل معرّفه واسمه وحالته والإجمالي والعدد المعالج والتقدم والطوابع الزمنية.

مثال:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk?status=processing&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

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

شكل استجابة قائمة المهام

{
  "jobs": [
    {
      "job_id": 42,
      "name": "September contacts",
      "status": "completed",
      "total": 1500,
      "processed": 1500,
      "progress": 100,
      "created_at": "2026-09-04T13:15:00+00:00",
      "completed_at": "2026-09-04T13:28:00+00:00"
    }
  ],
  "pagination": {"page": 1, "per_page": 20, "total": 1, "last_page": 1}
}

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

إلغاء مهمة

POST /api/v1/verify/bulk/{jobId}/cancel

ألغِ العمل المعلق أو قيد التشغيل فقط. الاستجابة الناجحة هي:

{"status":"cancelled","credits_refunded":40}

تخص إعادة الرصيد العمل غير المعالج. إذا وصلت المهمة إلى حالة نهائية قبل وصول الإلغاء، تعيد API تعارضًا بدلًا من تغيير نتيجتها.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"

لا يؤدي الإلغاء إلى حذف المهمة. نزّل الصفوف المعالجة إن لزم أو احذف السجل المكتمل بعد ذلك.

حذف مهمة

DELETE /api/v1/verify/bulk/{jobId}

ألغِ المهمة قيد التشغيل أولًا. يزيل الحذف المهمة ونتائجها نهائيًا بعد أن يزيل TrekMail القائمة المصدر المرحلية بأمان. الاستجابة الناجحة هي:

{"deleted":true}

curl -X DELETE https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 843ef0c5-4dc0-4c09-bacd-5bd0fe87e847"

هذه العملية نهائية لسجل أداة التحقق. وهي لا تسحب ملفات CSV التي نزّلها تطبيقك بالفعل، لذا طبّق عملية الاحتفاظ الخاصة بك على تلك النسخ.

ترتيب الحذف

1. اقرأ حالة المهمة.
2. ألغها إذا كانت معلقة أو قيد المعالجة.
3. احفظ أي تصدير معالج يجب الاحتفاظ به.
4. احذف مهمة التحقق غير قيد التشغيل باستخدام مفتاح منع التكرار.
5. أزل النسخ التي يحتفظ بها نظامك وفق قواعد الخصوصية والاحتفاظ لديه.

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

حد مسار التحقق الفردي هو 60 طلبًا في الدقيقة، وحد مسار الإرسال المجمع 10 طلبات في الدقيقة. أنشئ منطق إعادة محاولة يزيد وقت الانتظار، واحتفظ بالمفتاح نفسه لإعادة محاولة طلب مجمع، ولا تعد محاولة طلب دون تحقق بعد نتيجة شبكة مجهولة.

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

1. أنشئ مفتاح منع تكرار واحدًا وخزّنه قبل الإرسال المجمع.
2. أرسل الطلب بذلك المفتاح.
3. إذا فُقدت الاستجابة، فأعد الطلب المطابق بالمفتاح نفسه.
4. خزّن job_id المعاد وتوقف عن إنشاء عمليات إرسال جديدة لتلك القائمة المصدر.
5. استعلم عن المهمة حتى تصل إلى حالة نهائية، ثم نزّل نتيجتها أو عالجها.

في التحقق الفردي، تعني 503 المؤقتة أن الخدمة لم تتمكن من إكمال الفحص. أعد المحاولة لاحقًا مع زيادة وقت الانتظار المعتادة. لا تحوّل تلك الاستجابة إلى نتيجة Invalid في قاعدة بياناتك.

الحفاظ على أمان بيانات جهات الاتصال

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

يحتفظ TrekMail بالنتائج لمدة 15 يومًا. خطط لتخزين التصدير الآمن أو لمسار الحذف قبل دمج القوائم ذات الحجم الكبير.

لا تثبت مؤشرات التحقق ملكية الشخص أو موافقته أو التسليم المستقبلي. أبقِ معالجة الأذونات والمنع في تطبيقك حتى عندما يحصل العنوان على Safe.