واجهة للمطورين
واجهة بريد مؤقت لاستلام الرسالة في الاختبار
واجهة سراب ميل تنشئ عنوانًا على نطاق بريد، ثم تعيد الرسالة التي تصل إليه. الناس يبحثون عنها بأسماء متقاربة: temporary email API، وtemp mail API، وdisposable email API، وreceive email API. المسار واحد: مفتاح، ثم صندوق، ثم انتظار.
المصادقة
العنوان الأساسي في هذا النشر هو https://sarabmail.com/api/v1. أرسل المفتاح في Authorization: Bearer sm_live_… أو في الترويسة X-Api-Key. المفتاح يُحفظ كبصمة فقط.
أنشئ مفتاحًا مجانيًا من زر الوثائق أو بـ POST /api/v1/keys. الحقل key في الاستجابة هو السر، ويظهر هذه المرة فقط. إنشاء المفاتيح محدود بخمسة في الساعة لكل شبكة. الخطة المجانية تشمل 100 رسالة في الشهر على النطاقات العامة.
إنشاء صندوق ثم قراءة البريد
POST /api/v1/inboxes بجسم JSON فارغ {} ينشئ عنوانًا عشوائيًا على نطاق مسموح لخطتك، وليس على sarabmail.com. الاستجابة تحوي inbox.id و inbox.address. تستطيع إرسال localPart و domain إذا أردت اسمًا بعينه.
GET /api/v1/inboxes/{id}/messages/wait?timeout=8 يبقى مفتوحًا حتى تصل رسالة أو ينتهي الوقت. الخادم يقصّ timeout إلى حد قصير، 8 ثوانٍ في الإعداد الافتراضي، ولا يتجاوز 60. إذا لم يصل شيء فالاستجابة { "message": null } مع حالة 200. عند الوصول يحوي message.subject و message.textBody و message.htmlBody بعد التنقية. قائمة الرسائل على GET /api/v1/inboxes/{id}/messages تعيد ملخصات: id و fromAddress و fromName و subject و preview و receivedAt و attachmentCount.
ما لا تفعله الواجهة
لا ترسل بريدًا. تطبيقك، أو خادم البريد عندك، هو من يرسل إلى inbox.address. سراب ميل يسلّم ما يصل.
الصور البعيدة محجوبة إلا إذا أضفت images=1. الخطط التي تشمل الويب هوك تضبط PUT /api/v1/webhook بعنوان https، والتوقيع في X-SarabMail-Signature على شكل sha256=HMAC(secret, body). التفاصيل والأخطاء في وثائق الواجهة.
بداية سريعة
curl
curl -sS -X POST https://sarabmail.com/api/v1/inboxes \
-H "Authorization: Bearer $SARABMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
# Response: { "inbox": { "id": "...", "address": "...", ... } }
# Then wait. timeout is clamped by the server (8 seconds by default).
INBOX_ID="inbox id from the response"
curl -sS "https://sarabmail.com/api/v1/inboxes/$INBOX_ID/messages/wait?timeout=8" \
-H "Authorization: Bearer $SARABMAIL_API_KEY"
# { "message": null } means nothing arrived yet.
# Otherwise message.subject and message.textBody are the mail.Python
import os
import requests
base = "https://sarabmail.com/api/v1"
headers = {
"Authorization": f"Bearer {os.environ['SARABMAIL_API_KEY']}",
"Content-Type": "application/json",
}
created = requests.post(f"{base}/inboxes", headers=headers, json={})
created.raise_for_status()
inbox = created.json()["inbox"]
print(inbox["address"])
waited = requests.get(
f"{base}/inboxes/{inbox['id']}/messages/wait",
headers=headers,
params={"timeout": 8},
)
waited.raise_for_status()
message = waited.json()["message"]
if message is None:
print("No message yet. Call wait again.")
else:
print(message["subject"])
print(message["textBody"])Node.js
const base = "https://sarabmail.com/api/v1";
const headers = {
Authorization: `Bearer ${process.env.SARABMAIL_API_KEY}`,
"Content-Type": "application/json",
};
const created = await fetch(`${base}/inboxes`, {
method: "POST",
headers,
body: "{}",
});
if (!created.ok) throw new Error(`create inbox failed: ${created.status}`);
const { inbox } = await created.json();
console.log(inbox.address);
const waited = await fetch(`${base}/inboxes/${inbox.id}/messages/wait?timeout=8`, { headers });
if (!waited.ok) throw new Error(`wait failed: ${waited.status}`);
const { message } = await waited.json();
console.log(message?.subject ?? "No message yet. Call wait again.");curl · مفتاح مجاني
curl -sS -X POST https://sarabmail.com/api/v1/keys \
-H "Content-Type: application/json" \
-d '{"name":"qa"}'
# The secret is the "key" field. It is shown only in this response.أسئلة عن واجهة البريد
هل ترسل الواجهة البريد؟
لا. هي لاستلام البريد الذي يرسله نظامك إلى العنوان الذي أنشأته.
كيف أوثّق الطلب؟
بترويسة Authorization: Bearer والمفتاح، أو بترويسة X-Api-Key. المفتاح المجاني يُنشأ من صفحة الوثائق أو من POST /api/v1/keys.
هل توجد تجربة مجانية؟
نعم. API Free تشمل 100 رسالة في الشهر على النطاقات العامة، بلا بطاقة، ما دمت لم تبدأ دفع خطة أعلى. الخطط الأعلى وأسعارها في صفحة الأسعار.
لماذا ينتهي الانتظار سريعًا؟
timeout يُقصّ إلى حد قصير حتى يعمل الطلب على الاستضافة بلا خادم. الافتراضي 8 ثوانٍ. أعد الطلب، أو استخدم قائمة الرسائل، أو تيار الأحداث، إذا تأخر البريد.