نظرة عامة

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

كل استجابة هي JSON، بما في ذلك كل خطأ.
جميع الأوقات بتوقيت UTC بصيغة RFC 3339 — 2026-08-04T18:31:07Z.
معرّفات الرسائل سلاسل غير شفافة. لا تحاول تحليلها.
استقبال فقط. لا توجد نقطة نهاية ترسل بريداً، بحكم التصميم.

عنوان URL الأساسي

https://grabmail.io/api/v1

HTTPS فقط؛ يُعاد توجيه HTTP العادي. يعيش الإصدار في المسار، ولن يتغيّر شكل v1 من تحتك — أي تغيير جذري يحصل على رقم جديد.

المصادقة

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

على نطاق تملكه، يكون صندوق البريد خاصًا، فتحمل الطلبات مفتاحًا — وهو ما يثبت أن صندوق البريد ملكك. يُصدَر المفتاح عندما تحقق من النطاق، ويُعرض مرة واحدة، ولا يُخزَّن هنا إلا كتجزئة (hash):

Authorization: Bearer <your key>

المفتاح الخاطئ أو المفقود على نطاق خاص يجيب بـ 401 مع unauthorized. تُقارَن المفاتيح في زمن ثابت، فيستغرق المفتاح الخاطئ رفضه نفس وقت قبول المفتاح الصحيح.

نقاط النهاية

GET /api/v1/mailbox

كل ما ينتظر عند عنوان، الأحدث أولاً. هذا هو الاستدعاء الذي تستطلعه مجموعة اختباراتك.

المعاملات

الاسم	إدخال	النوع	مطلوب	الوصف
`address`	query	string	نعم	صندوق البريد المراد قراءته، مثل `k7fq2m@grabmail.io`.
`limit`	query	integer	لا	عدد الرسائل المُعادة في هذا النداء، 1–200. الافتراضي 50، الأحدث أولًا. يحدّ استجابة واحدة، لا صندوق البريد — استخدم `before` للقراءة بعده.
`before`	query	string	لا	`id` الخاص بأقدم رسالة لديك بالفعل؛ يُعيد الصفحة التي تليها. أعد إرسال حقل `next` من الاستجابة السابقة. عندما يكون `next` هو `null`، تكون قد حصلت على كل شيء.

مثال

عرض صندوق بريد

$ curl -G https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=k7fq2m@grabmail.io"

{
  "address": "k7fq2m@grabmail.io",
  "count": 1,
  "next": null,
  "messages": [
    {
      "id":          "01JR8W2K4Q",
      "from":        "no-reply@example.com",
      "subject":     "Your verification code",
      "date":        "2026-08-04T18:31:07Z",
      "seen":        false,
      "attachments": 0,
      "expires_at":  "2026-08-09T18:31:07Z"
    }
  ]
}

رموز الحالة

200: تمت قراءة صندوق البريد. صندوق البريد الفارغ هو 200 مع count: 0، وليس أبدًا 404. يحمل next مؤشر الصفحة التالية، أو null عند النهاية.
400: العنوان غير صحيح الصياغة، أو أن before ليس معرّف رسالة.
400: حقل address مفقود أو ليس عنوانًا صالحًا.
404: هذا النطاق غير مستضاف هنا — تحقق من سجل MX.
429: تم تجاوز حد المعدل. أعد المحاولة بعد المهلة المذكورة في Retry-After.

GET /api/v1/message/{id}

الترويسات، الجزء النصي، جزء HTML وأي مرفقات.

المعاملات

الاسم	إدخال	النوع	مطلوب	الوصف
`id`	path	string	نعم	معرّف الرسالة الذي أعاده نداء القائمة.
`mailbox`	query	string	نعم	العنوان الذي سُلّمت إليه الرسالة.

مثال

قراءة رسالة

$ curl -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "id":      "01JR8W2K4Q",
  "from":    "no-reply@example.com",
  "to":      "k7fq2m@grabmail.io",
  "subject": "Your verification code",
  "date":    "2026-08-04T18:31:07Z",
  "text":    "Your code is 481920. It expires in 10 minutes.",
  "html":    null,
  "attachments": []
}

رموز الحالة

200: الرسالة. يكون html هو null عندما يرسل المرسل نصًا عاديًا فقط.
400: حقل mailbox مفقود أو غير صالح.
404: لا رسالة كهذه في صندوق البريد هذا — أو أنها تجاوزت نافذة الاحتفاظ.
429: تم تجاوز حد المعدل.

DELETE /api/v1/message/{id}

يزيلها فوراً، بدلاً من انتظار انتهاء نافذة الاحتفاظ.

المعاملات

الاسم	إدخال	النوع	مطلوب	الوصف
`id`	path	string	نعم	الرسالة المراد إزالتها.
`mailbox`	query	string	نعم	العنوان الذي سُلّمت إليه.

مثال

حذف رسالة

$ curl -X DELETE -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "deleted": true,
  "id": "01JR8W2K4Q"
}

رموز الحالة

200: تم الحذف. النداء متكافئ الوقع (idempotent): حذفه مرتين لا يزال يُجيب بـ200.
400: حقل mailbox مفقود أو غير صالح.
404: لا رسالة كهذه في صندوق البريد هذا.
429: تم تجاوز حد المعدل.

المرفقات

تسرد كل رسالة مرفقاتها برابط جاهز. اجلبه بنفس التفويض المستخدم للرسالة نفسها.

GET /api/v1/attachment/{id}?mailbox={address}

يجيب دائمًا بـ application/octet-stream مع Content-Disposition: attachment، أيًّا كان ما وسمه به المُرسل. هذا مقصود: إعادة إظهار text/html الخاص بشخص غريب كما هو كانت ستسمح لمرفق بالعمل كصفحة على هذا المصدر. النوع الحقيقي موجود في JSON الرسالة، حيث هو بيانات لا تعليمات.

الأخطاء

كل فشل هو JSON بنفس الحقلين، بحيث يتعامل معه العميل في مكان واحد. تحمل الحالة الفئة، وerror رمز مختصر ثابت قابل للقراءة آليًا، وmessage موجَّه للبشر وقد تُعاد صياغته في أي وقت.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error":   "invalid_address",
  "message": "address must look like name@domain"
}

لا تُبنِ منطقك أبدًا على message. الرموز المختصرة المستخدمة هي invalid_address وunknown_domain و not_found وrate_limited.

حدود المعدل

طلب واحد في الثانية لكل عنوان. استطلاع صندوق البريد مرة في الثانية هو النمط المقصود ولا يُقيَّد أبدًا.

عند تجاوز الحد تحصل على 429 مع Retry-After بالثواني. لا توجد حصة يومية ولا رصيد اندفاع لإدارته.

الاحتفاظ

تُحذف الرسالة بعد 5 يومًا من وصولها، سواء قُرئت أم لا. تحمل كل رسالة expires_at، فلا تحتاج أبدًا لحساب ذلك التاريخ بنفسك.

إنه حد صارم، لا إعداد — لا معلمة تمدّده. إذا كان على رسالة أن تبقى بعد انتهاء النافذة، فاجلبها وخزّنها لديك.

نطاقك الخاص

وجّه سجل MX الخاص بك إلى smtp.grabmail.io ويجيب كل عنوان على نطاقك عبر نفس هذه النقاط الطرفية — لا واجهة برمجية ثانية لتعلّمها، ولا تُقرأ صناديق البريد إلا بمفتاحك.

ربط نطاق ←

مرجع API

نظرة عامة

عنوان URL الأساسي

المصادقة

نقاط النهاية

المعاملات

مثال

رموز الحالة

المعاملات

مثال

رموز الحالة

المعاملات

مثال

رموز الحالة

المرفقات

الأخطاء

حدود المعدل

الاحتفاظ

نطاقك الخاص