مرجع واجهة برمجة فحص البريد الإلكتروني

المصادقة

تقبل POST /v1/email/validate مفتاحًا قابلًا للنشر مقيَّدًا بالمصدر عبر الترويسة X-Api-Key — نوع المفتاح ونموذج المصادر المسموح بها نفسيهما في GET /v1/geo. أما جميع نقاط النهاية الأخرى في هذه الصفحة (المجمّعة، ومهام القوائم، وفحص التسجيل) فتقبل عناوين عديدة أو عنوان IP عشوائيًا، لذا تتطلب مفتاحك السري عبر Authorization: Bearer ويجب ألا تُستدعى إلا من الخلفية لديك؛ ويحصل المفتاح القابل للنشر فيها على 403.

مثال

curl https://api.watch-ip.com/v1/email/validate \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "John.Doe+news@Gmial.com"}'

{
  "email": "John.Doe+news@Gmial.com",
  "domain": "gmial.com",
  "syntaxValid": true,
  "isDisposable": false,
  "normalizedEmail": "john.doe+news@gmial.com",
  "canonicalEmail": "john.doe@gmial.com",
  "disposableSource": null,
  "isFreeProvider": false,
  "isRoleAccount": false,
  "didYouMean": "john.doe+news@gmail.com",
  "mx": {
    "status": "none",
    "host": null
  },
  "verdict": "reject",
  "reasons": [
    "no_mail_server",
    "typo_suspected"
  ]
}

الأحكام ورموز الأسباب

يفرض كل شرط حكمًا أدنى؛ ويغلب الأشد، وتسرد reasons جميع الشروط من الأشد إلى الأخف. أما قبول عنوان من مزوّد بريد مجاني فمتروك لتقديرك — لا يغيّر الحكم أبدًا.

الفحص المجمّع

POST/v1/email/batch

يفحص من 1 إلى 100 عنوان في طلب واحد بالفحوصات نفسها وشكل النتيجة نفسه في POST /v1/email/validate، نتيجة لكل عنوان بترتيب الإدخال. أرسل { "emails": [...] }. العناوين التي تشترك في النطاق نفسه تتشارك استعلام DNS واحدًا. يُحتسب طلب واحد لكل عنوان ضمن الحد الشهري لخطتك؛ والدفعة التي تتجاوز الحد تُرفض كاملةً مع 429 monthly_limit_exceeded. بالنسبة إلى حد المعدل في الدقيقة، يُحتسب الاستدعاء بأكمله طلبًا واحدًا. بالمفتاح السري فقط.

curl https://api.watch-ip.com/v1/email/batch \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user@gmail.com", "someone@mailinator.com"]}'

{
  "results": [
    { "email": "user@gmail.com", "verdict": "accept", "reasons": [], ... },
    { "email": "someone@mailinator.com", "isDisposable": true, "disposableSource": "list", "verdict": "reject", "reasons": ["disposable_domain"], ... }
  ]
}

مهام قوائم البريد الإلكتروني

POST/v1/email/jobs

يفحص حتى 100,000 عنوان في الخلفية. أرسل JSON بالشكل { "emails": [...], "filename": "..." } أو جسم text/csv لا يتجاوز 10 ميغابايت: يُستخدم العمود المعنون email (أو e-mail أو email address أو email_address أو mail، دون تمييز لحالة الأحرف)، أو العمود الأول إذا لم يسمِّه أي عنوان؛ ويُكتشف الفاصل تلقائيًا (الفاصلة أو الفاصلة المنقوطة أو علامة الجدولة). تُحتسب المهمة عند إنشائها — طلب واحد لكل عنوان مميّز (تطابق تام)، فتُفحص العناوين المكررة لكنها تُحتسب مرة واحدة — والقائمة التي تتجاوز حدك الشهري تُرفض كاملةً. إذا تعذّرت معالجة جزء من المهمة بعد إعادة المحاولات، تُعلَّم المهمة failed وتُعاد أرصدة الجزء غير المعالَج. يُجيب بـ 202 مع كائن المهمة. بالمفتاح السري فقط؛ ويمكن أيضًا رفع المهام نفسها وتنزيلها من صفحة Email lists في لوحة التحكم.

curl https://api.watch-ip.com/v1/email/jobs \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @newsletter.csv

{
  "id": "5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11",
  "status": "queued",
  "source": "api",
  "filename": null,
  "total": 12840,
  "credits": 12512,
  "processed": 0,
  "summary": null,
  "createdAt": "2026-09-28T10:00:00.000Z",
  "completedAt": null,
  "expiresAt": "2026-10-05T10:00:00.000Z"
}

حالة المهمة

GET/v1/email/jobs/{id}

يُرجع كائن المهمة نفسه. استعلم عنه دوريًا حتى تصبح الحالة completed؛ ولا يُحتسب الاستعلام.

نتائج المهمة

GET/v1/email/jobs/{id}/results

يُنزّل ملف CSV يتضمن صفًا لكل صف مُرسل، بترتيب الإرسال — بما في ذلك المكررة. الأعمدة: email وnormalized_email وverdict وreasons وsyntax_valid وis_disposable وdisposable_source وis_free_provider وis_role_account وdid_you_mean وmx_status وmx_host. تُفصل قيم reasons بفاصلة منقوطة، والخلايا الفارغة تعني null، ويكون mx_status فارغًا للعناوين غير صحيحة الصياغة (لم يُجرَ أي استعلام). العنوان غير الصالح الذي يبدأ بـ = أو + أو - أو @ تُضاف قبله علامة اقتباس مفردة حتى لا تنفّذه تطبيقات الجداول كصيغة. يُرجع 409 إلى أن تكتمل المهمة، و410 بعد انتهاء صلاحيتها. التنزيل لا يُحتسب.

curl https://api.watch-ip.com/v1/email/jobs/5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11/results \
  -H "Authorization: Bearer YOUR_SECRET_KEY" -o results.csv

فحص التسجيل

POST/v1/signup/check

يقيّم تسجيلًا انطلاقًا من عنوان بريده الإلكتروني وعنوان IP في استدعاء واحد، من الخلفية لديك عند إرسال نموذج التسجيل (فالحكم المحسوب في المتصفح يمكن تزويره). أرسل { "email": "...", "ip": "...", "userAgent": "..." } — الحقل userAgent اختياري. تتضمن الاستجابة نتيجة فحص البريد الإلكتروني الكاملة (email)، وبلد عنوان IP وASN الخاص به و— في الخطط التي تشمل بيانات الأمان — مؤشرات VPN/Tor/مركز البيانات/التهديد (ip)، وعمر نطاق البريد بالأيام وفق بيانات التسجيل العامة (RDAP) (emailDomainAgeDays، وتكون null إن كان غير معروف ولمزوّدي البريد الاستهلاكي المعروفين)، ودرجة من 0 إلى 100 (مجموع أوزان الأسباب أدناه، بحد أقصى 100)، وحكمًا: reject عند 60 فأكثر، وreview عند 25 فأكثر، وإلا accept. في خطة بلا بيانات أمان تكون ip.security هي null، وتستخدم الدرجة إشارات البريد فقط، وتتضمن reasons السبب ip_security_unavailable. يُحتسب طلبًا واحدًا. بالمفتاح السري فقط.

curl https://api.watch-ip.com/v1/signup/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@new-startup.io", "ip": "203.0.113.1"}'

{
  "email": { "email": "jane@new-startup.io", "verdict": "accept", "reasons": [], ... },
  "ip": {
    "ip": "203.0.113.1",
    "country": "US",
    "asn": 64500,
    "asOrganization": "Example Hosting",
    "security": { "isTor": false, "isVpn": false, "isDatacenter": true, "isThreat": false, "isSanctionedNetwork": false }
  },
  "emailDomainAgeDays": 12,
  "score": 45,
  "verdict": "review",
  "reasons": ["new_domain", "ip_datacenter"]
}

الحدود

كل عنوان مفحوص يُحتسب طلبًا واحدًا ضمن الحد الشهري المشترك لخطتك — الفحص الفردي، وكل عنوان في دفعة، وكل عنوان مميّز في مهمة قائمة — وفحص التسجيل طلب واحد. تُقبل الدفعات ومهام القوائم أو تُرفض كاملةً، ولا تُنفّذ جزئيًا أبدًا. يحتسب حد المعدل في الدقيقة استدعاءات HTTP لا العناصر: الدفعة التي تضم حتى 100 عنوان IP أو بريد إلكتروني تُحتسب طلبًا واحدًا، بينما يظل كل عنصر يُحتسب على حدة ضمن الحد الشهري للطلبات. تُحذف ملفات مهام القوائم المرفوعة ونتائجها بعد 7 أيام من إنشاء المهمة. لاستعلامات DNS مهلة زمنية قصيرة: عند فشل أحدها أو انتهاء مهلته تتراجع النتيجة إلى mx.status unknown والسبب dns_unavailable بدلًا من خطأ. بيانات النطاقات المؤقتة مدمجة من ثلاث قوائم مفتوحة المصدر يديرها المجتمع، وتُحدَّث كل بضع ساعات وتُوسَّع بخوادم البريد التي لوحظ أنها تخدم نطاقات مدرجة — انظر مصادر البيانات. قد لا يُرصد مزوّد مؤقت حديث جدًا بعد. جميع الفحوصات على مستوى النطاق والعنوان: لا يتم الاتصال بأي صندوق بريد، لذا لا تُثبت أي نتيجة وجود صندوق البريد أو هوية مالكه أو وصول الرسائل إليه.