نظرة عامة
يوفر RUN MAIL واجهة عامة مُصدَّرة لإنشاء الصناديق وقراءة الرسائل. زوار الموقع يستخدمون AJAX؛ التكاملات تستخدم مفاتيح API.
- العنوان الأساسي: https://run-mail.com/api/runmail/v1
- أجسام JSON للطلب والاستجابة
- أنواع الصناديق: temp و disposable و developer
- عمليات الصندوق تتطلب X-Mailbox-Token
المصادقة
أرسل مفتاحك كـ Authorization: Bearer أو X-Api-Key. بعد إنشاء صندوق، مرّر X-Mailbox-Token مع access_token من الاستجابة.
| Header | Example |
|---|
| Authorization |
Bearer rm_live_... |
| X-Api-Key |
rm_live_... |
| X-Mailbox-Token |
<access_token from create> |
الصلاحية:
*, mailboxes:read, mailboxes:write, messages:read, messages:write, domains:read, usage:read
زوار هذا الموقع لا يحتاجون مفتاح API — الوارد يستخدم جلسة عبر /ajax.
الصناديق
POST
/api/runmail/v1/mailboxes
mailboxes:write
إنشاء صندوق. يعيد email و uuid و access_token.
الطلب
JSON
{
"type": "temp | disposable | developer",
"ttl": 3600,
"local_part": "optional-local"
}
الاستجابة
JSON
{
"success": true,
"data": {
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"email": "[email protected]",
"access_token": "mbx_...",
"expires_at": 1710000000,
"type": "temp"
}
}
POST
/api/runmail/v1/mailboxes/rotate
mailboxes:write
تدوير صندوق موجود (عنوان ورمز جديدان).
Headers: X-Mailbox-Token
الطلب
JSON
{
"uuid": "mailbox-uuid",
"type": "temp",
"ttl": 7200
}
الاستجابة
JSON
{
"success": true,
"data": {
"uuid": "new-uuid",
"email": "[email protected]",
"access_token": "mbx_...",
"expires_at": 1710003600,
"type": "temp",
"rotated": true
}
}
GET
/api/runmail/v1/mailboxes/{uuid}
mailboxes:read
جلب بيانات الصندوق وعدد غير المقروء.
Headers: X-Mailbox-Token
الاستجابة
JSON
{
"success": true,
"data": {
"uuid": "uuid",
"email": "[email protected]",
"expires_at": 1710000000,
"type": "temp",
"status": "active",
"unread": 2
}
}
DELETE
/api/runmail/v1/mailboxes/{uuid}
mailboxes:write
حذف صندوق ورسائله.
Headers: X-Mailbox-Token
الاستجابة
JSON
{
"success": true,
"data": {
"deleted": true
}
}
POST
/api/runmail/v1/mailboxes/{uuid}/refresh
messages:read
فرض مزامنة/تحديث لمخزن الصندوق.
Headers: X-Mailbox-Token
الاستجابة
JSON
{
"success": true,
"data": {
"refreshed": true
}
}
الرسائل
GET
/api/runmail/v1/mailboxes/{uuid}/messages
messages:read
سرد رسائل الصندوق (مع ترقيم).
Headers: X-Mailbox-Token
المعاملات:
limit=1–100, cursor=optional
الاستجابة
JSON
{
"success": true,
"data": {
"messages": [
{
"uuid": "msg-uuid",
"subject": "Verify your account",
"from": "[email protected]",
"date": "2026-03-20T12:00:00Z"
}
],
"next_cursor": null
}
}
GET
/api/runmail/v1/mailboxes/{uuid}/messages/{message_uuid}
messages:read
جلب رسالة واحدة بما في ذلك الجسم.
Headers: X-Mailbox-Token
الاستجابة
JSON
{
"success": true,
"data": {
"uuid": "msg-uuid",
"subject": "Verify your account",
"from": "[email protected]",
"html": "<p>...</p>",
"text": "..."
}
}
DELETE
/api/runmail/v1/mailboxes/{uuid}/messages/{message_uuid}
messages:write
حذف رسالة واحدة.
Headers: X-Mailbox-Token
الاستجابة
JSON
{
"success": true,
"data": {
"deleted": true
}
}
النطاقات
GET
/api/runmail/v1/domains
domains:read
سرد نطاقات الاستقبال النشطة.
الاستجابة
JSON
{
"success": true,
"data": {
"domains": [
{
"domain": "example.com",
"active": true
}
]
}
}
الاستخدام والوقت الفعلي
GET
/api/runmail/v1/usage
usage:read
ملخص استخدام للمفتاح المصادق.
الاستجابة
JSON
{
"success": true,
"data": {
"requests": 120,
"period": "24h"
}
}
GET
/api/runmail/v1/ws-config
mailboxes:read
تلميح إعداد الوقت الفعلي / WebSocket.
الاستجابة
JSON
{
"success": true,
"data": {
"mode": "poll",
"wsUrl": ""
}
}
مفاتيح API
أنشئ المفاتيح وألغِها من صفحة مفاتيح API (للمسؤولين). يُعرض السر مرة واحدة عند الإنشاء.
احفظ المفاتيح في مدير أسرار. فضّل نطاقات صلاحية ضيقة بدل * عند الإمكان.
مفاتيح API
حدود المعدل
تُقيَّد الطلبات حسب IP ومفتاح API. تجاوز الحد يعيد HTTP 429.
- لاستعلام الموقع والمزامنة ميزانيات منفصلة.
- إنشاء/تدوير API يخضع لحماية الإساءة نفسها.
- أعد المحاولة بتأخير عشوائي عند استلام 429.
الأخطاء
الفشل يعيد success: false مع كائن error.
JSON
{
"success": false,
"error": {
"code": "rm_auth",
"message": "Invalid API key"
}
}
| HTTP | Meaning |
|---|
| 401 |
مفتاح API مفقود أو غير صالح |
| 403 |
صلاحية غير كافية أو عدم تطابق رمز الصندوق |
| 429 |
تم تجاوز الحد — أبطئ |
| 500 |
فشل خادم أو مزود |