مستندات واجهة برمجة تطبيقات التحقق من صحة البريد الإلكتروني

الشروع في العمل

تتطلب جميع طلبات واجهة برمجة التطبيقات مصادقة باستخدام مفتاح واجهة برمجة التطبيقات. يمكنك العثور على مفتاح API الخاص بك في لوحة التحكم.

الرأس: "x-api-key: your-api-keykey"

التحقق الفردي

تحقق من عنوان بريد إلكتروني واحد أو نطاق واحد للتحقق من صلاحيته وحالة التخلص منه وخدمات الخصوصية وإمكانية التسليم.

نقطة النهاية

GET /v1/verify

المعلمات

الاسم	النوع	مطلوب	الوصف
input	string	نعم	عنوان البريد الإلكتروني أو النطاق المراد التحقق منه (على سبيل المثال، [email protected] أو example.com)

حقول الاستجابة

الحقل	الوصف
valid	يشير إلى ما إذا كان تنسيق البريد الإلكتروني صحيحاً أم لا
block	يشير إلى ما إذا كان يجب حظر البريد الإلكتروني (صواب إذا كان البريد الإلكتروني الذي يمكن التخلص منه أو الخصوصية أو ApplePrivateEmail أو قابل للتسليم أو قابل للتوصيل أو قابل للتوصيل أو قابل للتوصيل)
disposable	يحدد ما إذا كان عنوان البريد الإلكتروني عنوان بريد إلكتروني مؤقت أو يمكن التخلص منه
privacy	يحدد ما إذا كان خادم البريد يستخدم اسمًا مستعارًا للبريد الإلكتروني أو معيد توجيه البريد الإلكتروني
applePrivateEmail	تشير إلى ما إذا كان البريد الإلكتروني هو عنوان بريد إلكتروني خاص بشركة Apple
deliverable	التحقق مما إذا كان صندوق البريد موجوداً ويمكنه استقبال رسائل البريد الإلكتروني
domain	جزء المجال من عنوان البريد الإلكتروني
email_address	عنوان البريد الإلكتروني
catch_all	يشير إلى ما إذا كان المجال يحتوي على تكوين بريد إلكتروني شامل يقبل جميع رسائل البريد الإلكتروني الواردة بغض النظر عن عنوان المستلم
mx_found	يشير إلى ما إذا كان المجال يحتوي على خوادم بريد صالحة (سجلات MX)
remaining_credits	عدد أرصدة واجهة برمجة التطبيقات (API) المتبقية في حسابك

القائمة السوداء/القائمة البيضاء: يعكس حقل الحظر فقط عضوية القائمة. القائمة السوداء → الحظر: صواب؛ القائمة البيضاء → الحظر: خطأ؛ ليس في القائمة البيضاء (عند التمكين) → الحظر: صواب. لا تستخدم صالح لتحديد ما إذا كان سيتم الحظر بناءً على القوائم.

مثال على الاستجابة

{
  "valid": true,
  "block": false,
  "disposable": false,
  "privacy": false,
  "applePrivateEmail": false,
  "deliverable": true,
  "domain": "example.com",
  "email_address": "[email protected]",
  "catch_all": false,
  "mx_found": true,
  "error": null,
  "remaining_credits": 99
}

أمثلة على الرموز

curl "https://api.verify-email.app/v1/[email protected]" \
  -H "X-API-Key: your-api-key"

جربها

مفتاح واجهة برمجة التطبيقات

تحتاج إلى مفتاح API لاختبار نقاط النهاية.

عنوان البريد الإلكتروني أو النطاق

جرب مع:

التحقق من الدُفعات

تحقق من عناوين بريد إلكتروني أو نطاقات بريد إلكتروني متعددة في طلب واحد (بحد أقصى 100 عنصر).

نقطة النهاية

POST /v1/verify/batch

المعلمات

الاسم	النوع	مطلوب	الوصف
inputs	array of strings	نعم	مجموعة من عناوين البريد الإلكتروني أو المجالات للتحقق منها

أمثلة على الرموز

curl -X POST "https://api.verify-email.app/v1/verify/batch" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "inputs": [
      "[email protected]",
      "[email protected]"
    ]
  }'

جربها

مفتاح واجهة برمجة التطبيقات

تحتاج إلى مفتاح API لاختبار نقاط النهاية.

عناوين البريد الإلكتروني أو النطاقات

جرّب مع نطاقات مختلفة:

الشيك القابل للتسليم فقط

التحقق السريع من إمكانية تسليم البريد الإلكتروني باستخدام التحقق من MX و SMTP دون الحاجة إلى مكالمات واجهة برمجة التطبيقات الخارجية. إرجاع الحقول المتعلقة بقابلية التسليم فقط للحصول على أوقات استجابة أسرع.

نقطة النهاية

GET /v1/verify/deliverable

المعلمات

الاسم	النوع	مطلوب	الوصف
input	string	نعم	عنوان البريد الإلكتروني للتحقق من إمكانية التسليم (على سبيل المثال، [email protected]). إدخال المجال فقط غير مدعوم لنقطة النهاية هذه.

حقول الاستجابة

الحقل	الوصف
valid	يشير إلى ما إذا كان تنسيق البريد الإلكتروني صحيحاً أم لا
deliverable	التحقق مما إذا كان صندوق البريد موجوداً ويمكنه استقبال رسائل البريد الإلكتروني
mx_found	يشير إلى ما إذا كان المجال يحتوي على خوادم بريد صالحة (سجلات MX)
catch_all	يشير إلى ما إذا كان المجال يحتوي على تكوين بريد إلكتروني شامل يقبل جميع رسائل البريد الإلكتروني الواردة بغض النظر عن عنوان المستلم
email_address	عنوان البريد الإلكتروني
remaining_credits	عدد أرصدة واجهة برمجة التطبيقات (API) المتبقية في حسابك

مثال على الاستجابة

{
  "valid": true,
  "deliverable": true,
  "mx_found": true,
  "catch_all": false,
  "email_address": "[email protected]",
  "remaining_credits": 99
}

أمثلة على الرموز

curl "https://api.verify-email.app/v1/verify/[email protected]" \
  -H "X-API-Key: your-api-key"

جربها

مفتاح واجهة برمجة التطبيقات

تحتاج إلى مفتاح API لاختبار نقاط النهاية.

عنوان البريد الإلكتروني أو النطاق

جرب مع:

القائمة البيضاء والقائمة السوداء

تحكّم في حظر البريد أو النطاقات عبر قواعد القائمة السوداء والبيضاء لكل مستخدم. هذه القوائم تحدّد حقل block في كل استجابة تحقق.

{}

حقل block

كل استجابة تحقق تتضمن حقل block. راجع هذا الحقل لمعرفة ما إذا يجب حظر البريد/النطاق حسب قوائمك:

trueالبريد أو نطاقه في القائمة السوداء → block: true. إضافة نطاق تحظر كل العناوين عليه.

trueالقائمة البيضاء مفعّلة لكن البريد/النطاق غير موجود فيها → block: true.

falseالقائمة البيضاء مفعّلة والبريد أو نطاقه موجود فيها → block: false.

—لا تنطبق أي قائمة → block يتبع نتيجة التحقق العادية.

نظرة عامة

✘

القائمة السوداء

حظر بريد أو نطاقات محددة دائماً. مثلاً إضافة example.com للقائمة السوداء تعني أن أي بريد @example.com سيعيد block: true بغض النظر عن نتيجة التحقق.

✔

القائمة البيضاء

السماح فقط ببريد أو نطاقات محددة. عند تفعيل القائمة البيضاء، المدخلات المدرجة فقط تحصل على block: false وكل شيء آخر block: true. مثلاً إضافة gmail.com تسمح بأي @gmail.com بينما [email protected] سيُحظر. عند التعطيل لا تأثير للقائمة البيضاء.

يمكنك إضافة بريد كامل ([email protected]) أو نطاق (example.com). إضافة نطاق تنطبق على كل البريد عليه. لا يُفرق بين الأحرف الكبيرة والصغيرة.

كيف يعمل

ترتيب التقييم

القائمة السوداء أولاً — إن كان البريد أو نطاقه في القائمة السوداء فالنتيجة block: true. لا يُطبّق منطق قوائم إضافي.

القائمة البيضاء (إن مُفعّلة) — إن كان البريد/النطاق في القائمة البيضاء → block: false. وإلا → block: true.

القائمة البيضاء معطّلة — تُطبّق القائمة السوداء والتحقق العادي فقط.

القائمة السوداء لها الأولوية دائماً. عنوان في القائمة السوداء يبقى محظوراً حتى لو كان في البيضاء أيضاً.

ما يُقارن

التحقق من البريد — تتحقق الواجهة من العنوان الكامل والنطاق مقابل القائمتين. أي تطابق يطبّق قاعدة القائمة.

التحقق من النطاق — يُتحقق من النطاق فقط مقابل القائمة السوداء و(إن مُفعّلة) البيضاء.

مرجع سريع

القائمة البيضاء مفعّلة	في القائمة السوداء	في القائمة البيضاء	قيمة block
لا	نعم	—	`true`
لا	لا	—	عادي
نعم	نعم	أي	`true`
نعم	لا	نعم	`false`
نعم	لا	لا	`true`

نقاط نهاية قوائم API

جميع نقاط نهاية القوائم تتطلب الرأس: X-API-Key: your-api-key

القائمة السوداء

GET/v1/blacklist

عرض إدخالات القائمة السوداء

POST/v1/blacklist

إضافة بريد أو نطاق · { "value": "..." }

DELETE/v1/blacklist

إزالة إدخال · value=...

القائمة البيضاء

GET/v1/whitelist

عرض إدخالات القائمة البيضاء

POST/v1/whitelist

إضافة بريد أو نطاق · { "value": "..." }

DELETE/v1/whitelist

إزالة إدخال · value=...

GET/v1/whitelist/enabled

الحصول على حالة القائمة البيضاء · { "enabled": boolean }

PUT/v1/whitelist/enabled

تفعيل/تعطيل القائمة البيضاء · { "enabled": true | false }

أمثلة على الرموز (cURL)

✘

القائمة السوداء

GET/v1/blacklist

عرض إدخالات القائمة السوداء

curl "https://api.verify-email.app/v1/blacklist" \
  -H "X-API-Key: your-api-key"

POST/v1/blacklist

إضافة بريد أو نطاق

curl -X POST "https://api.verify-email.app/v1/blacklist" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "value": "[email protected]"
  }'

DELETE/v1/blacklist

إزالة إدخال

curl -X DELETE "https://api.verify-email.app/v1/[email protected]" \
  -H "X-API-Key: your-api-key"

✔

القائمة البيضاء

GET/v1/whitelist

عرض إدخالات القائمة البيضاء

curl "https://api.verify-email.app/v1/whitelist" \
  -H "X-API-Key: your-api-key"

POST/v1/whitelist

إضافة بريد أو نطاق

curl -X POST "https://api.verify-email.app/v1/whitelist" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "value": "[email protected]"
  }'

DELETE/v1/whitelist

إزالة إدخال

curl -X DELETE "https://api.verify-email.app/v1/[email protected]" \
  -H "X-API-Key: your-api-key"

GET/v1/whitelist/enabled

الحصول على حالة القائمة البيضاء

curl "https://api.verify-email.app/v1/whitelist/enabled" \
  -H "X-API-Key: your-api-key"

PUT/v1/whitelist/enabled

تفعيل/تعطيل القائمة البيضاء

curl -X PUT "https://api.verify-email.app/v1/whitelist/enabled" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "enabled": true
  }'

تنسيق القيمة

[email protected] — البريد: تنسيق صالح مثل [email protected]
example.com — النطاق: تنسيق صالح مثل example.com

القيم غير الصالحة تُرفض برمز 400. تُخزّن الإدخالات بشكل طبيعي. التكرارات تُدمج في إدخال واحد.

أين تُطبّق القوائم

قواعد القوائم تُطبّق بعد التحقق. استجابات التحقق الفردي والدفعي للبريد والنطاق تتضمن بالفعل القائمة السوداء والبيضاء للمستخدم في حقل block.

خادم MCP (تكامل وكيل الذكاء الاصطناعي)

دمج التحقق من البريد الإلكتروني مباشرةً في وكلاء الذكاء الاصطناعي مثل Cursor وClaude Desktop باستخدام بروتوكول سياق النموذج (MCP). يمكن لمساعد الذكاء الاصطناعي الخاص بك التحقق من رسائل البريد الإلكتروني والتحقق من المجالات والتحقق من صحة بناء الجملة دون مغادرة المحرر.

Docs endpoint for AI agents

The API exposes a machine-readable docs endpoint (no API key required) so AI agents and MCP clients can discover the server, available tools, and auth requirements. Use this URL in your agent or MCP configuration.

GET /v1/mcp/docs

Returns JSON with server name, description, serverUrl, docsEndpoint, authentication details, and full tool definitions.

curl "https://api.verify-email.app/v1/mcp/docs"

AI agents can GET this URL to receive server metadata, tool schemas, and integration instructions in JSON. No authentication is required for the docs endpoint.

Open docs endpoint How to add in Cursor How to add in Claude

Integration details

Authentication

All MCP tool calls require your API key in the X-API-Key header. Get your key from the dashboard.

MCP server URL: https://api.verify-email.app/mcp

Docs endpoint (for agents): https://api.verify-email.app/v1/mcp/docs

Cursor

Add the server in Cursor Settings → Tools & MCP, or add the config to .cursor/mcp.json in your project or home directory.

Claude Desktop

Add the server to your Claude Desktop config (mcpServers in claude_desktop_config.json). Use the server URL and X-API-Key header as shown below.

Response format

Tool results match the REST API response shape (valid, block, deliverable, remaining_credits, etc.). Use the block field for blacklist/whitelist decisions.

This MCP server is production-ready and uses the same API as the REST endpoints. Credits are consumed per verification as with the REST API.

الإعداد

أضف التكوين التالي إلى ملف التكوين .cursor/mcp.json أو Claude Desktop config:

{
  "mcpServers": {
    "email-checker": {
      "url": "https://api.verify-email.app/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

الأدوات المتاحة

الأداة	الوصف	المدخلات	الاعتمادات
verify_email	التحقق الكامل من صحة البريد الإلكتروني بما في ذلك التحقق من بناء الجملة و MX و SMTP والمتاح والخصوصية وإمكانية التسليم	{ email: string }	1
verify_domain	التحقق الكامل من النطاقات بما في ذلك سجلات MX، والمتاح، والخصوصية، والكشف عن كل شيء	{ domain: string }	1
check_deliverability	التحقق السريع من قابلية التسليم فقط باستخدام التحقق من MX و SMTP دون الحاجة إلى مكالمات واجهة برمجة تطبيقات خارجية	{ email: string }	1
verify_batch	التحقق الدفعي لما يصل إلى 100 بريد إلكتروني أو مجال في طلب واحد	{ inputs: string[] }	1 per item
validate_email_syntax	التحقق السريع من صحة بناء الجملة المحلي مقابل RFC 5322 دون الحاجة إلى إجراء مكالمات الشبكة	{ email: string }	0 (free)