البدء السريع مع API لخدمة Email Verifier

استخدم API عندما يلزم أن يكون التحقق جزءا من منتجك أو سير عمل الاستيراد لديك. أنشئ رمزا بنطاقي verify:read وverify:write، واحتفظ بسريته، واتصل بالمضيف نفسه الذي تستخدمه لتسجيل الدخول. في الأمثلة، استبدل https://YOUR-TREKMAIL-HOST وYOUR_API_TOKEN.

1. إنشاء رمز

1. افتح لوحة التحكم ← AI Agents & API.
2. أنشئ رمزا.
3. فعل verify:read وverify:write.
4. خزّن الرمز بأمان. لا يظهر إلا مرة واحدة.

أرسله مع كل طلب:

Authorization: Bearer YOUR_API_TOKEN

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

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

استخدم POST /api/v1/verify للحصول فورا على نتيجة عنوان واحد. يكون Quick هو الوضع الافتراضي عند حذف mode.

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"}'

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

{
  "email": "person@example.com",
  "status": "valid",
  "trust_score": 82,
  "provider": "example.com",
  "risk_factors": ["no_dmarc"],
  "checks": {
    "syntax": {"pass": true, "score_impact": 0},
    "dmarc_record": {"pass": false, "score_impact": -10}
  },
  "credits_remaining": {
    "monthly": 99,
    "purchased": 0
  }
}

اقرأ status وtrust_score أولا. تعامل مع مفاتيح الفحوص الفردية باعتبارها تفاصيل داعمة، لا ضمانا لملكية صندوق البريد أو التسليم.

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

3. إرسال مهمة مجمعة

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

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

يمكن أن تحتوي القائمة على ما يصل إلى 50,000 إدخال. يوحد TrekMail الإدخالات المكررة ويرفض الإدخالات غير الصالحة نحويا من المهمة. تعرض الاستجابة معرف المهمة وعدد الإدخالات المقبولة وعينة صغيرة من المرفوضات والأرصدة المحتسبة وتفصيل تسعير Deep.

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

probe هو العدد المحتسب بسعر Deep الكامل. وskip هو العدد المحتسب بالسعر العادي لأن مزود الخدمة لا يقدم أدلة مفيدة على مستوى صندوق البريد. تقدم الاستجابة التكلفة المعتمدة لذلك الإرسال.

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

4. استطلاع الحالة وتنزيل النتائج

استطلع المهمة باستخدام GET /api/v1/verify/bulk/{jobId} حتى تصل إلى حالة نهائية:

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

تتضمن الاستجابة status وtotal وprocessed وprogress وsummary ووقت الإنشاء ووقت الإكمال. وتتضمن المهام المكتملة والمكتملة جزئيا مصفوفة results مقسمة إلى صفحات.

استطلع على فترات معقولة مع زيادة مهلة الانتظار تدريجيا. قد تبقى المهمة معلقة قبل بدء العمل، وقد يستغرق عمل Deep وقتا أطول عندما يقدم مزود الخدمة المستقبل أدلة إضافية. لا تفترض وقت إكمال ثابتا بناء على حجم القائمة وحده.

يمكنك طلب صفحة نتائج أصغر أو البحث عن عنوان معروف بعد توفر النتائج:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42?per_page=50&search=%40example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

نزّل مهمة معالجة بتنسيق CSV:

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

فلاتر تصدير API هي all وsafe وsafe_risky (Safe + Valid + Risky).

لإيقاف مهمة معلقة أو قيد التشغيل، استخدم endpoint الإلغاء. يعيد الأرصدة عن العمل غير المعالج ويحتفظ بأي صفوف معالجة:

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

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

5. التعامل مع الاستجابات المعتادة

• 402: يحتاج الحساب إلى مزيد من الأرصدة.
• 422: تحقق من نص الطلب أو الوضع المحدد أو مفتاح عدم التأثر بالتكرار المطلوب للطلب المجمع.
• 429: اخفض معدل الطلبات وأعد المحاولة مع زيادة مهلة الانتظار تدريجيا.
• 503: التحقق غير متاح مؤقتا. أعد المحاولة لاحقا، ويعاد رصيد التحقق الفردي الفاشل.

قائمة تحقق لتكامل الإنتاج

1. احتفظ بالرمز من جهة الخادم وامنح فقط نطاقي Verifier المطلوبين.
2. تحقق من إدخال جهات الاتصال ووحده قبل استدعاء API المجمع.
3. خزّن معرف المهمة ومعرف القائمة المرسلة ومفتاح عدم التأثر بالتكرار وقيمة credits_charged المعادة.
4. استخدم الاستطلاع مع زيادة مهلة الانتظار بدلا من حلقة سريعة.
5. خزّن CSV أو عالجه قبل انتهاء فترة الاحتفاظ البالغة 15 يوما.
6. احتفظ بقرارات الموافقة وإلغاء الاشتراك والاستبعاد في تطبيقك. لا تحل نتيجة أداة التحقق محلها.

استخدم مرجع REST API لخدمة Email Verifier لجميع endpoints والنطاقات وحقول الاستجابة.