افتح صندوق بريد

مرجع API

ثلاث نقاط طرفية، JSON دخولًا وخروجًا. لا مفتاح ولا حساب على النطاقات العامة — ألصق طلبًا في طرفية وسيعمل.

نظرة عامة

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

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

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

https://grabmail.io/api/v1

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

المصادقة: غير مطلوبة

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

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

بيانات الاعتماد الوحيدة في هذه الواجهة هي مفتاح حسابك، الموصوف أدناه — مفتاح واحد للحساب المجاني، وأكثر في الخطط المدفوعة. ليس للمفتاح مستوى خاص به: يُحكم على كل استدعاء وفق الخطة التي يملكها حسابه في تلك اللحظة، لذا يتخلص المفتاح نفسه من الحدود المجانية ويفتح المجمّع المميز فور اشتراكك، ثم يعود إلى الحصة المجانية عند انتهاء الخطة. لا تحتاج النطاقات العامة إلى مفتاح؛ وإن أُرسل معها احتُسبت استدعاءاتك لحسابك بدلًا من عنوان IP الخاص بك. المفتاح المُرسَل إن كان غير معروف أو مُبطَلًا يُجيب بـ 401 مع unauthorized على كل نقطة نهاية، أيًّا كان النطاق — فيظهر الخطأ المطبعي فورًا بدلاً من أن يبدو صندوق بريد فارغًا.

النطاقات المميّزة

الاستثناء الوحيد للقاعدة أعلاه. النطاقات العامة مدرجة في قوائم حظر البريد المؤقت، ولهذا يرفض نموذج التسجيل أحيانًا عنوانًا عليها. تفتح الخطة المدفوعة مجمّعًا من 97 نطاقًا .com خاصًا، خارج تلك القوائم.

لا يتغيّر شيء في API. المسارات نفسها، والمعاملات نفسها، وأشكال الاستجابة نفسها. الفرق الوحيد ترويسة واحدة: يُقرأ العنوان المميز بـ Authorization: Bearer gm_live_…، بمفتاح من مفاتيح الواجهة لديك. وبلا مفتاح من خطة مدفوعة، يجيب الطلب نفسه بـ 404 — وهي بالحرف نفسه إجابة نطاق لا نستضيفه، عن قصد، حتى لا يمكن حصر المجمّع بتخمين الأسماء. لا صندوق بريد أبدًا.

أين توجد نطاقات المجمّع

يُعيد GET /api/v1/domains مع مفتاحك النطاقات العامة وأسماء نطاقات المجمّع. النداء نفسه بلا مفتاح — أو بمفتاح من حساب مجاني أو منتهي الصلاحية — يُعيد النطاقات العامة وعدد النطاقات التي يضمّها المجمّع وتكلفته، لكن لا يُعيد اسمًا أبدًا: إبقاؤها خارج القوائم السوداء للبريد المؤقت هو ما تشتريه الخطة. كما يرى المشترك المسجَّل دخوله المجمّع في منتقي النطاقات على الصفحة الرئيسية.

curl -s https://grabmail.io/api/v1/domains \
  -H "Authorization: Bearer gm_live_…"

{
  "public": ["grabmail.io", "mixozia.com", "linqmail.com"],
  "premium": {
    "count": 97,
    "unlocked": true,
    "domains": ["one-of-the-pool.com", "another-of-the-pool.com", "…"]
  }
}

التحقق من المفتاح

GET /api/v1/me هو النداء الوحيد الذي يحكم على المفتاح وحده: 200 مع الخطة والفترة الحالية والحصة المستهلكة والمتبقية والعناوين المحتفَظ بها وحد المعدل الخاص بك — أو 401 unauthorized إذا كان المفتاح غير معروف أو مُبطَلًا. استدعه أولاً حين يجيب شيء في المجمّع بـ 404: تلك الإجابة تُخفي مشكلة في المفتاح عن قصد، وهذا النداء يكشفها.

curl -s https://grabmail.io/api/v1/me \
  -H "Authorization: Bearer gm_live_…"

{
  "plan": "premium",
  "status": "active",
  "premium": true,
  "period": { "start": "2026-09-14T00:00:00Z", "end": "2026-10-14T00:00:00Z" },
  "usage": { "messages": 12, "addresses": 5, "consumed": 12, "quota": 2000, "left": 1988, "over": false },
  "addresses_held": 5,
  "limits": { "requests_per_second": 2, "requests_per_minute": null, "requests_per_day": null, "api_keys": 1, "address_cap": null },
  "pool": { "count": 97, "access": true, "domains": "GET https://grabmail.io/api/v1/domains" }
}

ماذا يُجيب المجمّع

كل حالة، وسببها. الحالتان الأوليان هما اللتان تبدوان مفاجئتين إلى أن تُقرأ العلّة.

404
unknown_domain — بلا مفتاح، أو بمفتاح من حساب مجاني أو منتهي الصلاحية. مطابق عن قصد لإجابة نطاق لا نستضيفه: فالتمييز بينهما كان سيسمح بحصر المجمّع بتخمين الأسماء. تحقّق من المفتاح عبر /api/v1/me.
401
unauthorized — المفتاح المُرسَل غير معروف أو مُبطَل. يُجاب به على كل نقطة نهاية أيًّا كان النطاق: فهو يقول شيئًا عن المفتاح، لا عن نطاق أبدًا.
402
quota_reached — نفدت حصة هذه الفترة والتجاوز معطّل. overage_cap / overage_funds — التجاوز مفعّل، لكن السقف الذي حددته بلغته أو الرصيد غير كافٍ. العناوين المحتفَظ بها بالفعل تستمر في العمل في الحالات الثلاث.
403
address_taken — يحتفظ مشترك آخر بذلك العنوان. اختر اسمًا آخر.
409
address_limit — مخصَّص لخطة تضع سقفًا لعدد العناوين. لا توجد خطة كذلك اليوم.
429
rate_limited — في الخطة المجانية (بلا مفتاح أو بمفتاح مجاني): طلبات تتجاوز 60 في الدقيقة، أو أكثر من قراءة واحدة في الثانية على عنوان واحد؛ وبمفتاح مدفوع: أكثر من 2 أو 3 أو 5 قراءات في الثانية على عنوان واحد. daily_limit_reached — نفدت الطلبات المجانية لهذا اليوم، وعددها 1,000. والخطط المدفوعة لا تخضع لسقف الدقيقة ولا للسقف اليومي. ويحمل كلاهما Retry-After.

العناوين المحتفَظ بها والحصة

يُحتفَظ بالعنوان المميز لأول حساب يقرؤه بمفتاح صالح — أي قراءة، على أي نقطة نهاية أو عبر MCP، دون أي حجز مسبق. وطوال احتفاظه به، لا يقرؤه سوى ذلك الحساب؛ وأي حساب آخر يحصل على 403. ويبقى محتفَظًا به حتى تُطلقه من لوحة التحكم، أو تنتهي الخطة — في تاريخ انتهائها، دون فترة سماح.

تحسب الحصة وحدات: رسالة تصل إلى عنوان مميز أو عنوان مميز جديد يُفتح، أيهما أسبق — فالعنوان الذي تفتحه ولا تقرأه أبدًا يستهلك وحدة مع ذلك. أما إعادة قراءة عنوان محتفَظ به فمجانية. لا تحدّ أي خطة عدد العناوين التي يحتفظ بها الحساب؛ الحصة هي ما يقيّد ذلك، ويُظهر /api/v1/me ما تبقّى منها.

الاسم المستعار، في العناوين المميزة أيضًا

يحمل كل عرض لصندوق بريد حقل alias: عنوانًا ثانيًا يوصّل إلى الصندوق نفسه ولا يكشف عنه شيئًا. أعطِ الاسم المستعار لنموذج واستطلع العنوان به؛ فمن يملك الاسم المستعار يرى صندوق بريد فارغًا دائمًا. وهو ثابت لعنوان معيّن، ومجاني، ويُعاد للعناوين المميزة تمامًا كما للعناوين العامة. نطاقه أحد نطاقاتنا ولا يُدرَج في أي مكان عن قصد.

كل شيء، في أربعة نداءات

KEY="gm_live_…"   # من صفحة مفاتيح الواجهة البرمجية لديك، بخطة مدفوعة
# 1. تحقّق من المفتاح: الخطة، والحصة المتبقية، وحد المعدل. 401 إن كان غير صالح.
curl -s https://grabmail.io/api/v1/me -H "Authorization: Bearer $KEY"

# 2. اعرض المجمّع. الأسماء في الإجابة فقط مع مفتاح مدفوع.
curl -s https://grabmail.io/api/v1/domains -H "Authorization: Bearer $KEY"

# 3. اقرأ صندوق بريد على أحدها. هذه القراءة الأولى تحتفظ بالعنوان وتُحتسب وحدة واحدة.
curl -sG https://grabmail.io/api/v1/mailbox -H "Authorization: Bearer $KEY" \
  --data-urlencode "address=a7f3k2@one-of-the-pool.com"

# 4. اقرأ رسالة واحدة، بالترويسة نفسها.
curl -sG https://grabmail.io/api/v1/message/MESSAGE_ID -H "Authorization: Bearer $KEY" \
  --data-urlencode "mailbox=a7f3k2@one-of-the-pool.com"

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

نقاط النهاية

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",
  "alias": "hq8kd2m4p7zt@alias-domain.example",
  "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 عند النهاية. وalias عنوان ثانٍ يوصّل إلى هنا ولا يكشف شيئًا عن هذا العنوان — أعطه لنموذج بدلاً من address؛ فمن يملكه يرى صندوق بريد فارغًا دائمًا. وهو ثابت ومجاني، ويُعاد للعناوين المميزة أيضًا.
400
العنوان غير صحيح الصياغة، أو أن before ليس معرّف رسالة.
400
حقل address مفقود أو ليس عنوانًا صالحًا.
401
أُرسل مفتاح API وهو غير معروف أو مُبطَل. يُرفض المفتاح الخاطئ على كل نطاق؛ والنطاقات العامة لا تحتاج إلى أي مفتاح أصلاً.
402
المجمّع المميز فقط: نفدت حصة الخطة — quota_reached، أو overage_cap / overage_funds إذا كان التجاوز مفعّلاً. العناوين المحتفَظ بها بالفعل تستمر في العمل.
403
المجمّع المميز فقط: يحتفظ مشترك آخر بذلك العنوان (address_taken).
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 وbad_cursor وunknown_domain وnot_found وrate_limited وdaily_limit_reached وunauthorized، وفي المجمّع المميز وحده quota_reached وoverage_cap وoverage_funds وaddress_taken وaddress_limit.

تحمل بعض الأخطاء أكثر من هذين الحقلين: hint يقول ماذا تفعل، ورابط docs، وفي 404 و429 كتلة premium_pool بسعر المجمّع وكيفية فتحه، وفي 429 الناتج عن الحد المجاني كتلة upgrade تبيّن ما ترفعه الخطة المدفوعة — وكل ذلك مكتوب من أجل مساعد يقرأ نص الاستجابة نيابةً عن شخص ما، حتى ينقل إليه الخيار بدل أن يستسلم.

حدود المعدل

مجانًا وبلا مفتاح: الطلبات حتى 60 في الدقيقة و1,000 في اليوم، لكل عنوان IP. يُحتسب كل نداء على صندوق البريد — سرده، وقراءة رسالة، ونصها بصيغة HTML، ومرفق، والحذف — وكذلك كل استدعاء لأداة MCP. ويُصفَّر العدّ اليومي عند 00:00 UTC.

مع مفتاح API مجاني، تتبع الحصة نفسها حسابك بدلًا من عنوان IP الخاص بك — وهذا مفيد عندما تصدر استدعاءاتك من عناوين متغيرة، مثل مشغّل CI. للحساب المجاني مفتاح واحد، والصناديق التي يقرأها تُدرج في صناديقك. إنشاء مفتاح مجاني

وضمن ذلك، قراءة واحدة في الثانية لكل عنوان: استطلاع صندوق البريد مرة كل ثانية هو الإيقاع المقصود.

الخطط المدفوعة بلا سقف في الدقيقة وبلا سقف يومي. أرسل مفتاح خطة مدفوعة كـ Authorization: Bearer فلا يبقى إلا معدل الخطة لكل عنوان — 2 أو 3 أو 5 طلبات في الثانية، على كل النطاقات، ويُحتسب لكل حساب على حدة. وتبدأ خطة Premium من $12.99 شهريًا. عرض الخطط

صندوق الوارد على هذا الموقع لا يستهلك من الحصة المجانية لواجهة API: فالصفحة التي تتركها مفتوحة تواصل التحقق من وصول البريد ما دمت تحتاج إليها.

عند تجاوز أحد الحدود تحصل على 429 مع ترويسة Retry-After بالثواني الصحيحة: rate_limited لحد الدقيقة أو حد العنوان، وdaily_limit_reached لحد اليوم، مع الوقت المتبقي حتى منتصف الليل بتوقيت UTC. وتُبيّن كل استجابة مجانية ما تبقّى لك: X-RateLimit-Remaining للدقيقة، وX-RateLimit-Daily-Remaining لليوم.

الاحتفاظ

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

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

نطاقك الخاص

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

ربط نطاق ←

اللغة

أهلًا بعودتك

صناديقك ونطاقاتك في مكان واحد.

القائمة

المنتج

المطورون

الشركة

قانوني

اللغة

مجاني · بلا تسجيل · تُحذف بعد 5 أيام

عنوان جديد

صندوق بريد عام — يمكن لأي شخص يعرف العنوان قراءته.