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

المصادقة

أرسل المفتاح في الترويسة Authorization: Bearer sm_live_… أو في X-Api-Key. المفتاح يُحفظ كبصمة SHA-256 فقط.

المفتاح المجاني يُنشأ من هذه الصفحة. حد الإنشاء خمسة مفاتيح في الساعة لكل شبكة.

curl https://sarabmail.com/api/v1/usage \
  -H "Authorization: Bearer sm_live_…"

المستويات

مفتاح الواجهة المجاني: 100 رسالة في الشهر على نطاقات البريد العامة. Starter: 5000. Team: 50000 مع نطاق فرعي خاص. Business: 300000 مع 3 نطاقات خاصة. Enterprise من $299.

Plus للأشخاص: $3.99 شهريًا أو $29 سنويًا، بلا إعلانات، و10 صناديق، وحفظ 30 يومًا، ونطاقات أقل انكشافًا. Pro: $7.99 أو $59 سنويًا، صناديق دائمة، ونطاق خاص، وتحويل، وواجهة خفيفة. الدفع عبر Paddle عندما تُضبط المفاتيح.

الصناديق

POST /inboxes ينشئ عنوانًا على نطاق من مجموعة البريد، لا على sarabmail.com. اترك الجسم فارغًا لعنوان عشوائي، أو أرسل localPart و domain. ttlMinutes يُقيَّد بسقف خطتك. permanent: true لخطط Pro و Business و Enterprise.

curl -X POST https://sarabmail.com/api/v1/inboxes \
  -H "Authorization: Bearer sm_live_…" \
  -H "Content-Type: application/json" \
  -d '{"domain":"inbox.example"}'

الرسائل

GET /inboxes/{id}/messages يعيد الملخصات. GET للرسالة الواحدة يعيد النص و HTML بعد التنقية. الصور البعيدة محجوبة إلا إذا أضفت ?images=1.

الحذف: DELETE على الرسالة أو على الصندوق.

الانتظار

GET /inboxes/{id}/events يبقي اتصال أحداث SSE قصيرًا ويستيقظ عبر إشعار Postgres عند وصول البريد. GET /inboxes/{id}/messages/wait?timeout=8 يبقى مفتوحًا حتى تصل رسالة أو ينتهي الوقت. المهلة قصيرة كي تعمل على الاستضافة بلا خادم.

curl "https://sarabmail.com/api/v1/inboxes/INBOX_ID/messages/wait?timeout=8" \
  -H "Authorization: Bearer sm_live_…"

ويب هوك

الخطط التي تشمل الويب هوك تستطيع PUT /webhook مع عنوان https. نرسل JSON بحدث message.received، والتوقيع في X-SarabMail-Signature على شكل sha256=HMAC(secret, body). السر يُعاد عند ضبط العنوان.

النطاقات

GET /domains يعرض نطاقات خطتك. Pro و Business تضيف نطاقًا عبر POST /domains ثم تضع سجل TXT بالقيمة sarabmail-verify=… وتستدعي POST /domains/verify. Team و Business تطلب نطاقًا فرعيًا عبر POST /domains/subdomain بجسم { "label": "acme" }. البريد لا يصل قبل توجيه البريد في Cloudflare أو سجل MX.

الأخطاء

الشكل دائمًا { "error": { "code", "message" } }. 401 للمفتاح، و403 لحد الخطة، و409 للعنوان المحجوز، و429 مع Retry-After عند تجاوز المعدل. الترويسات X-RateLimit-Limit و Remaining و Reset تُرسل مع الطلبات المصادق عليها.