وثائق REST API

GET/api/email/{domain}/{user}/

الحصول على قائمة مرقّمة برسائل البريد الإلكتروني للمستخدم. تحتوي استجابات القائمة على بيانات التعريف فقط (لا body / html_body).

المعلمة	موقع	وصف
domain	طريق	مجال البريد الإلكتروني، على سبيل المثال. example.com
user	طريق	اسم المستخدم، على سبيل المثال. testuser
page	الاستعلام، اختياري	رقم الصفحة (الافتراضي 1)
limit	الاستعلام، اختياري	العناصر في كل صفحة (الافتراضي 20، والحد الأقصى 100)

curl -X GET "https://BASE_URL/api/email/example.com/testuser/?page=1&limit=20"

{
  "emails": [
    {
      "id": 123,
      "subject": "Welcome",
      "sender": "[email protected]",
      "date": "2026-09-30T10:30:00.000Z",
      "has_attachments": false,
      "size": 1234
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20,
  "has_more": false
}

GET/api/email/{domain}/{user}/{email_id}

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

curl -X GET "https://BASE_URL/api/email/example.com/testuser/123"

DELETE/api/email/{domain}/{user}/{email_id}

حذف بريد إلكتروني محدد.

curl -X DELETE "https://BASE_URL/api/email/example.com/testuser/123"

{ "status": "deleted" }

POST/api/add-domain/{domain}

أضف مجالًا جديدًا أو قم بتحديث حالة الاتصال بنطاق موجود. يجب أن يحتوي المجال على سجل MX يشير إلى اسم مضيف النظام حتى يتم قبوله (الحالة added, is_online: true).

curl -X POST "https://BASE_URL/api/add-domain/newdomain.com"

// تمت الإضافة بنجاح
{ "status": "added", "domain": "newdomain.com", "is_online": true }

// المجال الموجود: قم بتحديث حالته
{ "status": "updated", "domain": "newdomain.com", "is_online": false }

GET/api/all-domains/ & /api/random-domains/

جميع النطاقات عبر الإنترنت (خاصة، مطلوب رمز مميز):

curl -X GET "https://BASE_URL/api/all-domains/" \
  -H "X-Domain-Token: YOUR_TOKEN"

النطاقات العشوائية على الإنترنت (العامة):

curl -X GET "https://BASE_URL/api/random-domains/?limit=10"

{ "domains": ["domain1.com", "domain2.com"], "total": 2 }

GET/api/check-mx/{domain}

تحقق مما إذا كان المجال يحتوي على سجل MX صالح يشير إلى النظام.

curl -X GET "https://BASE_URL/api/check-mx/example.com"

{ "result": "online" }   // أو "offline"

معالجة الأخطاء

شفرة	معنى
200	نجاح
400	طلب غير صالح (على سبيل المثال، نطاق/بريد إلكتروني تالف)
401	رمز مفقود أو غير صالح لنقطة نهاية خاصة
404	لم يتم العثور على البريد الإلكتروني
429	تم تجاوز الحد الأقصى للسعر

{ "detail": "Domain not found" }

ملاحظات مهمة

• يجب أن تستخدم عناوين البريد الإلكتروني التنسيق [email protected]
• النطاقات التي تحتوي على سجلات MX صالحة هي فقط التي تتمتع بحالة "متصل".
• يتم حذف رسائل البريد الإلكتروني والمجالات غير النشطة تلقائيًا بعد ذلك 3 أيام
• الخدمة فقط يستقبل البريد الإلكتروني - لا يتم دعم الإرسال والترحيل عبر SMTP
• تطبق واجهة برمجة التطبيقات (API) حدود معدل لكل IP
• تنطبق فترة الاحتفاظ البالغة 3 أيام على الخدمة المباشرة؛ قد تحتفظ النسخ الاحتياطية بالنسخ لفترة أطول. ولا يمكن ضمان الحذف الدائم من جميع النسخ في ذلك الوقت.
• تظل صناديق البريد الوارد للنطاق المخصص عامة وقد يتم حظرها بواسطة خدمات خارجية. القبول والتسليم غير مضمونين.