وثائق واجهة البرمجة

نظرة عامة

يوفر RUN MAIL واجهة عامة مُصدَّرة لإنشاء الصناديق وقراءة الرسائل. زوار الموقع يستخدمون AJAX؛ التكاملات تستخدم مفاتيح API.

العنوان الأساسي: /api/runmail/v1
أجسام JSON للطلب والاستجابة
أنواع الصناديق: temp و disposable و developer
عمليات الصندوق تتطلب X-Mailbox-Token

Base URL

/api/runmail/v1

المصادقة

أرسل مفتاحك كـ 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": 1710007200,
        "type": "temp"
    }
}

GET /api/runmail/v1/mailboxes/{uuid} mailboxes:read

جلب بيانات الصندوق وعدد غير المقروء.

Headers: X-Mailbox-Token

الاستجابة

JSON

{
    "success": true,
    "data": {
        "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "email": "[email protected]",
        "expires_at": 1710000000,
        "type": "temp"
    }
}

DELETE /api/runmail/v1/mailboxes/{uuid} mailboxes:write

docs_ep_delete_mb

Headers: X-Mailbox-Token

الاستجابة

JSON

{
    "success": true,
    "data": {
        "deleted": true
    }
}

الرسائل

GET /api/runmail/v1/mailboxes/{uuid}/messages messages:read

سرد رسائل الصندوق (مع ترقيم).

Headers: X-Mailbox-Token

المعاملات: limit=50, offset=0

الاستجابة

JSON

{
    "success": true,
    "data": {
        "messages": [
            {
                "id": "msg_1",
                "from": "[email protected]",
                "to": "[email protected]",
                "subject": "Verify your email",
                "received_at": 1710000100
            }
        ],
        "total": 1
    }
}

GET /api/runmail/v1/mailboxes/{uuid}/messages/{id} messages:read

جلب رسالة واحدة بما في ذلك الجسم.

Headers: X-Mailbox-Token

الاستجابة

JSON

{
    "success": true,
    "data": {
        "id": "msg_1",
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Verify your email",
        "text": "Your code is 123456",
        "html": "<p>Your code is <strong>123456</strong></p>",
        "received_at": 1710000100
    }
}

DELETE /api/runmail/v1/mailboxes/{uuid}/messages/{id} messages:write

docs_ep_delete_msg

Headers: X-Mailbox-Token

الاستجابة

JSON

{
    "success": true,
    "data": {
        "deleted": true
    }
}

النطاقات

GET /api/runmail/v1/domains domains:read

docs_ep_list_domains

الاستجابة

JSON

{
    "success": true,
    "data": {
        "domains": [
            {
                "domain": "example.com",
                "status": "active"
            }
        ]
    }
}

الاستخدام والوقت الفعلي

GET /api/runmail/v1/usage usage:read

ملخص استخدام للمفتاح المصادق.

الاستجابة

JSON

{
    "success": true,
    "data": {
        "mailboxes_created": 12,
        "messages_received": 48,
        "period": "30d"
    }
}

مفاتيح 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	فشل خادم أو مزود

توثيق API

نظرة عامة

المصادقة

الصناديق

الطلب

الاستجابة

الطلب

الاستجابة

الاستجابة

الاستجابة

الرسائل

الاستجابة

الاستجابة

الاستجابة

النطاقات

الاستجابة

الاستخدام والوقت الفعلي

الاستجابة

مفاتيح API

حدود المعدل

الأخطاء