مفاتيح API
واجهة API متاحة لحسابات بريميوم فقط. للاشتراك، افتح تذكرة في الديسكورد
المفتاح يُعرض مرة واحدة عند إنشائه. الحد 5 مفاتيح لكل حساب.
مرجع الواجهة
عنوان الأساس
https://509.lol/api/v1
المصادقة
كل طلب يحمل المفتاح في ترويسة Authorization بصيغة Bearer.
Authorization: Bearer sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA
المفتاح يبدأ بـ sab_live_ ويتبعه 32 حرفاً، ويُعرض مرة واحدة عند إنشائه في هذه اللوحة. إنشاء المفاتيح وإلغاؤها يتم من هنا لا عبر الواجهة.
الواجهة لحسابات بريميوم. مفتاح حساب غير مشترك يُرفض بالرمز PREMIUM_REQUIRED، والمفتاح الملغى يُرفض بالرمز KEY_REVOKED.
شكل الاستجابة
الاستجابة الناجحة تحمل success: true والبيانات داخل data. الفاشلة تحمل success: false ونص error ورمز errorCode من جدول الأخطاء.
{ "success": true, "data": { } }{ "success": false, "error": "Domain not available for this account", "errorCode": "DOMAIN_FORBIDDEN" }GET
/api/v1/meيُرجع الحساب المرتبط بالمفتاح، وحصة العناوين المحجوزة، وحالة حد الإنشاء الحالية.
الترويسات
| الترويسة | القيمة | الوصف |
|---|---|---|
Authorization | Bearer sab_live_... | إلزامي. المفتاح بصيغة Bearer |
الطلب
curl https://509.lol/api/v1/me \ -H "Authorization: Bearer sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA"
الاستجابة 200
{
"success": true,
"data": {
"username": "acme",
"accountType": "premium",
"reserved": { "used": 12, "max": 50, "remaining": 38 },
"rateLimit": {
"limit": 100,
"windowSeconds": 60,
"remaining": 97,
"resetAt": "2026-09-09T12:31:00.000Z"
}
}
}حقول الاستجابة
| الحقل | النوع | الوصف |
|---|---|---|
username | string | اسم المستخدم |
accountType | string | premium أو admin |
reserved | object | العناوين المحجوزة: used و max و remaining |
rateLimit | object | حد الإنشاء: limit و windowSeconds و remaining و resetAt بصيغة ISO 8601 |
GET
/api/v1/domainsيُرجع الدومينات المتاحة للحساب. الدومين الذي يحمل isPrimary: true هو الافتراضي عند إنشاء عنوان بلا domain.
الترويسات
| الترويسة | القيمة | الوصف |
|---|---|---|
Authorization | Bearer sab_live_... | إلزامي. المفتاح بصيغة Bearer |
الطلب
curl https://509.lol/api/v1/domains \ -H "Authorization: Bearer sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA"
الاستجابة 200
{
"success": true,
"data": {
"domains": [
{ "domain": "sirabody.com", "tier": "free", "isPrimary": true },
{ "domain": "509.lol", "tier": "free", "isPrimary": false },
{ "domain": "cyberpath.pro", "tier": "premium", "isPrimary": false }
]
}
}حقول الاستجابة
| الحقل | النوع | الوصف |
|---|---|---|
domain | string | اسم الدومين كما يُمرَّر في domain |
tier | string | free أو premium |
isPrimary | boolean | الدومين الافتراضي |
POST
/api/v1/emailsيحجز عنواناً أو أكثر باسم الحساب.
الترويسات
| الترويسة | القيمة | الوصف |
|---|---|---|
Authorization | Bearer sab_live_... | إلزامي. المفتاح بصيغة Bearer |
Content-Type | application/json | إلزامي مع جسم JSON |
حقول الطلب
| الحقل | النوع | القيود |
|---|---|---|
prefix | string اختياري | الجزء قبل @. من 3 إلى 30 حرفاً من a-z و 0-9 مع حرف واحد على الأقل، وليس اسماً محجوزاً. عند غيابه يولّد الخادم بادئة عشوائية مقبولة. |
domain | string اختياري | أحد الدومينات من GET /domains. الافتراضي الدومين الأساسي. |
count | integer اختياري | عدد العناوين. من 1 إلى 25، الافتراضي 1. |
الطلب
curl -X POST https://509.lol/api/v1/emails \
-H "Authorization: Bearer sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA" \
-H "Content-Type: application/json" \
-d '{"prefix":"acme42","domain":"509.lol"}'الاستجابة 201
{
"success": true,
"data": {
"created": [
{
"address": "[email protected]",
"prefix": "acme42",
"domain": "509.lol",
"reservedAt": "2026-09-09T12:30:12.000Z"
}
],
"failed": []
}
}قد ينجح جزء من الطلب. ما حُجز يظهر في created، وما تعذّر يظهر في failed مع رمز الخطأ لكل عنصر. الحالة 201 ما دام الطلب نفسه صحيحاً.
عنوانان ببادئات مولَّدة
curl -X POST https://509.lol/api/v1/emails \
-H "Authorization: Bearer sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA" \
-H "Content-Type: application/json" \
-d '{"count":2}'{
"success": true,
"data": {
"created": [
{ "address": "[email protected]", "prefix": "k7x2mq9v", "domain": "sirabody.com", "reservedAt": "2026-09-09T12:32:40.000Z" },
{ "address": "[email protected]", "prefix": "p3zt8w1n", "domain": "sirabody.com", "reservedAt": "2026-09-09T12:32:40.000Z" }
],
"failed": []
}
}بادئة محجوزة
curl -X POST https://509.lol/api/v1/emails \
-H "Authorization: Bearer sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA" \
-H "Content-Type: application/json" \
-d '{"prefix":"admin"}'{
"success": true,
"data": {
"created": [],
"failed": [
{ "prefix": "admin", "domain": "sirabody.com", "errorCode": "NAME_FORBIDDEN", "error": "This name is reserved" }
]
}
}حقول الاستجابة
| الحقل | النوع | الوصف |
|---|---|---|
created[] | address, prefix, domain, reservedAt | العناوين التي حُجزت |
failed[] | prefix, domain, errorCode, error | ما تعذّر حجزه، مع رمز الخطأ ونصه لكل عنصر |
GET
/api/v1/emailsيُرجع العناوين المحجوزة للحساب، صفحةً صفحة.
الترويسات
| الترويسة | القيمة | الوصف |
|---|---|---|
Authorization | Bearer sab_live_... | إلزامي. المفتاح بصيغة Bearer |
معاملات الاستعلام
| المعامل | النوع | القيود |
|---|---|---|
page | integer اختياري | رقم الصفحة، يبدأ من 1. الافتراضي 1. |
limit | integer اختياري | عدد العناصر في الصفحة. القيم فوق 100 تُخفَّض إلى 100. |
الطلب
curl "https://509.lol/api/v1/emails?page=1&limit=50" \ -H "Authorization: Bearer sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA"
الاستجابة 200
{
"success": true,
"data": {
"emails": [
{
"address": "[email protected]",
"prefix": "acme42",
"domain": "509.lol",
"reservedAt": "2026-09-09T12:30:12.000Z"
},
{
"address": "[email protected]",
"prefix": "k7x2mq9v",
"domain": "sirabody.com",
"reservedAt": "2026-09-09T12:32:40.000Z"
}
],
"page": 1,
"limit": 50,
"total": 12
}
}total هو عدد كل العناوين المحجوزة، لا عدد عناصر الصفحة.
DELETE
/api/v1/emails/:addressيسحب حجز العنوان.
الترويسات
| الترويسة | القيمة | الوصف |
|---|---|---|
Authorization | Bearer sab_live_... | إلزامي. المفتاح بصيغة Bearer |
معاملات المسار
| المعامل | النوع | القيود |
|---|---|---|
address | string | العنوان الكامل مع الدومين. عنوان لا يملكه الحساب يُرجع NOT_FOUND. |
الطلب
curl -X DELETE https://509.lol/api/v1/emails/[email protected] \ -H "Authorization: Bearer sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA"
الاستجابة 200
{ "success": true }GET
/api/v1/emails/:address/messagesيُرجع رسائل عنوان يملكه الحساب، الأحدث أولاً، بلا أجسام الرسائل. عنوان لا يملكه الحساب يُرجع NOT_FOUND، وسحب الحجز يقطع القراءة فوراً.
الترويسات
| الترويسة | القيمة | الوصف |
|---|---|---|
Authorization | Bearer sab_live_... | إلزامي. المفتاح بصيغة Bearer |
معاملات المسار
| المعامل | النوع | القيود |
|---|---|---|
address | string | العنوان الكامل مع الدومين. عنوان لا يملكه الحساب يُرجع NOT_FOUND. |
معاملات الاستعلام
| المعامل | النوع | القيود |
|---|---|---|
page | integer اختياري | رقم الصفحة، يبدأ من 1. الافتراضي 1. |
limit | integer اختياري | عدد الرسائل في الصفحة. الافتراضي 25، والقيم فوق 100 تُخفَّض إلى 100. |
since | string اختياري | تاريخ ISO 8601. يُرجع ما وصل بعده فقط، وهو ما يُستخدم للاستقصاء بدل جلب الصندوق كاملاً كل مرة. |
الطلب
curl "https://509.lol/api/v1/emails/[email protected]/messages?limit=25" \ -H "Authorization: Bearer sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA"
الاستجابة 200
{
"success": true,
"data": {
"address": "[email protected]",
"messages": [
{
"id": "<[email protected]>",
"from": "Example <[email protected]>",
"subject": "Your verification code",
"date": "2026-09-10T09:14:22.000Z",
"preview": "Your code is 481920. It expires in 10 minutes.",
"hasHtml": true
}
],
"page": 1,
"limit": 25,
"total": 1
}
}حقول الاستجابة
| الحقل | النوع | الوصف |
|---|---|---|
id | string | معرّف الرسالة. يُستخدم في مسار قراءة الرسالة الواحدة. |
from | string | المرسِل كما وصل في الرسالة. نص يتحكم به المرسِل، لا تثق به. |
subject | string | الموضوع |
date | string | تاريخ الرسالة بصيغة ISO 8601 |
preview | string | أول 240 محرفاً من النص المجرّد |
hasHtml | boolean | هل للرسالة جسم HTML يُجلب من مسار الرسالة الواحدة |
total | integer | عدد الرسائل المطابقة كاملاً، لا عدد ما في هذه الصفحة |
GET
/api/v1/emails/:address/messages/:idيُرجع رسالة واحدة كاملة، نصاً وHTML.
معاملات المسار
| المعامل | النوع | القيود |
|---|---|---|
address | string | العنوان الكامل مع الدومين. عنوان لا يملكه الحساب يُرجع NOT_FOUND. |
id | string | معرّف الرسالة من قائمة الرسائل. 400 محرف كحد أقصى، ويجب ترميزه في المسار. |
الطلب
MSG=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" '<[email protected]>') curl "https://509.lol/api/v1/emails/[email protected]/messages/$MSG" \ -H "Authorization: Bearer sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA"
الاستجابة 200
{
"success": true,
"data": {
"id": "<[email protected]>",
"address": "[email protected]",
"from": "Example <[email protected]>",
"subject": "Your verification code",
"date": "2026-09-10T09:14:22.000Z",
"text": "Your code is 481920. It expires in 10 minutes.",
"html": "<div>Your code is <b>481920</b></div>",
"htmlTruncated": false,
"attachments": []
}
}حقول الاستجابة
| الحقل | النوع | الوصف |
|---|---|---|
text | string | النص المجرّد. هذا ما تُستخرج منه الأكواد عادةً. |
html | string | جسم HTML كما وصل، غير معالَج. يتحكم به المرسِل، فلا تُدخله في صفحة دون تعقيم أو إطار معزول. |
htmlTruncated | boolean | true إذا تجاوز الجسم 256 كيلوبايت وقُطع |
attachments | array | فارغة دائماً. المنصة لا تحفظ المرفقات. |
DELETE
/api/v1/emails/:address/messages/:idيحذف رسالة واحدة من الصندوق.
الطلب
curl -X DELETE "https://509.lol/api/v1/emails/[email protected]/messages/$MSG" \ -H "Authorization: Bearer sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA"
الاستجابة 200
{ "success": true }DELETE
/api/v1/emails/:address/messagesيفرّغ صندوق العنوان. الحجز نفسه يبقى.
الطلب
curl -X DELETE https://509.lol/api/v1/emails/[email protected]/messages \ -H "Authorization: Bearer sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA"
الاستجابة 200
{ "success": true, "data": { "deleted": 3 } }عنوان جديد ثم قراءة كوده
التسلسل الكامل: أنشئ عنواناً، استعمله عند الخدمة، ثم استقصِ الصندوق بـ since حتى تصل الرسالة.
KEY="sab_live_4kq9Xw2mZp7Lc0vR8tYb3nHfJ1sDgUeA"
BASE="https://509.lol/api/v1"
ADDR=$(curl -s -X POST "$BASE/emails" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"509.rip"}' | python3 -c 'import json,sys;print(json.load(sys.stdin)["data"]["created"][0]["address"])')
SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
echo "$ADDR"
for i in $(seq 1 60); do
BODY=$(curl -s "$BASE/emails/$ADDR/messages?since=$SINCE&limit=1" -H "Authorization: Bearer $KEY")
echo "$BODY" | grep -q '"total": 0' || { echo "$BODY"; break; }
sleep 2
doneاستقصِ كل ثانيتين لا أسرع. سقف الطلبات 600 في الدقيقة لكل حساب، ومئة عنوان تُستقصى كل ثانية تستهلكه بالكامل.
حدود الاستخدام
100 عنوان جديد في الدقيقة لكل حساب. الحد مشترك بين كل مفاتيح الحساب، وإنشاء مفتاح إضافي لا يرفعه.
كل استجابة من /api/v1 تحمل الترويسات التالية. عند التجاوز تُرجع 429 مع Retry-After.
| الترويسة | الوصف |
|---|---|
RateLimit-Limit | سقف النافذة |
RateLimit-Remaining | المتبقي في النافذة الحالية |
RateLimit-Reset | الثواني حتى تتجدد النافذة |
Retry-After | مع 429 فقط. الثواني قبل إعادة المحاولة |
استجابة 429
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 42
Retry-After: 42
{ "success": false, "error": "Rate limit exceeded", "errorCode": "RATE_LIMITED" }الأخطاء
كل خطأ يحمل الشكل نفسه. errorCode ثابت ومخصص للمقارنة في الكود، بينما error نص للقراءة قد يتغيّر.
| الرمز | HTTP | السبب |
|---|---|---|
UNAUTHORIZED | 401 | لا ترويسة Authorization، أو الرمز ليس مفتاح API (لا يبدأ بـ sab_) |
INVALID_KEY | 401 | المفتاح بالصيغة الصحيحة لكنه لا يطابق أي مفتاح |
KEY_REVOKED | 401 | المفتاح أُلغي من اللوحة |
PREMIUM_REQUIRED | 403 | الحساب ليس بريميوم |
ACCOUNT_SUSPENDED | 403 | الحساب موقوف |
RATE_LIMITED | 429 | أكثر من 100 عنوان في الدقيقة الحالية |
QUOTA_EXCEEDED | 403 | الحساب بلغ حد العناوين المحجوزة |
DOMAIN_FORBIDDEN | 403 | الدومين غير معروف أو غير متاح للحساب |
NAME_FORBIDDEN | 400 | البادئة تخالف السياسة: صيغة غير صحيحة أو اسم محجوز |
NAME_TAKEN | 409 | البادئة محجوزة لحساب آخر على هذا الدومين |
INVALID_REQUEST | 400 | جسم غير صالح، أو حقل خارج نطاقه، مثل count أكبر من 25 |
NOT_FOUND | 404 | العنوان أو المفتاح غير موجود أو لا يملكه الحساب |
SERVER_ERROR | 500 | خطأ داخلي، أعد المحاولة لاحقاً |
داخل failed في POST /emails تظهر الرموز نفسها لكل عنصر مع بقاء حالة الاستجابة 201.