مرجع API

واجهة REST API للبريد الإلكتروني المعاملاتي

تقبل الواجهة الطلبات المصادَق عليها، وتتحقق من نطاق المشروع وحالة النطاق، وتفحص قوائم الإيقاف، ثم تُدرج الرسائل المقبولة في قائمة الانتظار.

2026-10-13تنزيل OpenAPI 3.1

المصادقة

POST /v1/emails

الطلب / الاستجابة

curl --request POST 'https://api.srs-postline.com/v1/emails' \
  --header 'Authorization: Bearer srs_live_...' \
  --header 'Idempotency-Key: order_4821' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "from": "Postline <info@example.com>",
    "to": ["user@example.net"],
    "subject": "Your order is ready",
    "html": "<p>Order #4821 is ready.</p>",
    "text": "Order #4821 is ready."
  }'

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "id": "msg_01JPOSTLINEEXAMPLE",
  "status": "queued",
  "created_at": "2026-08-22T12:00:00Z"
}

معلمات الإدخال

المعلمة	النوع	مطلوب	الوصف	مثال
`Authorization`	`header · string`	نعم	مفتاح API محدود الصلاحيات صادر من لوحة التحكم بصيغة رمز Bearer.	`Bearer srs_live_…`
`Idempotency-Key`	`header · string`	لا	معرّف ثابت لعملية إرسال منطقية واحدة؛ يوصى به بشدة.	`order_4821`
`from`	`string`	نعم	اسم المرسل وعنوانه على نطاق تم التحقق منه.	`Postline <info@example.com>`
`to`	`string[]`	نعم	من عنوان بريد واحد إلى 100 عنوان للمستلمين.	`["user@example.net"]`
`subject`	`string`	نعم	موضوع الرسالة.	`طلبك جاهز`
`html`	`string`	لا	محتوى HTML. يجب توفير html أو text.	`<p>…</p>`
`text`	`string`	لا	محتوى نصي عادي. يجب توفير text أو html.	`الطلب #4821…`

رموز الاستجابة

الحالة	HTTP	الوصف
`202`	Accepted	تم وضع الرسالة في قائمة الانتظار؛ وهذا لا يعني وصولها إلى صندوق الوارد.
`400`	Bad Request	JSON غير صالح أو حقول غير مدعومة.
`401`	Unauthorized	مفتاح API غير صالح أو منتهي الصلاحية أو ملغى.
`403`	Forbidden	النطاق scope مفقود أو نطاق المرسل غير موثّق.
`422`	Unprocessable Entity	المستلم موجود في قائمة المنع.
`429`	Too Many Requests	تم تجاوز حد طلبات المشروع.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "recipient suppressed"
}

إرسال بريد إلكتروني

POST /v1/emails
Authorization: Bearer srs_live_…
Idempotency-Key: reset-4821
Content-Type: application/json

الموارد الأساسية

POST/v1/emailsإدراج رسالة في قائمة الانتظار

GET/v1/emails/{id}فحص حالة الرسالة

POST/v1/domainsإضافة نطاق إرسال

POST/v1/domains/{id}/verifyتشغيل فحوصات DNS

GET/POST/DELETE/v1/suppressionsإدارة المستلمين الموقوفين

GET/POST/DELETE/v1/webhooksإدارة نقاط أحداث webhook

نموذج الاستجابة

الرمز 202 يعني أن الرسالة أُدرجت في قائمة الانتظار وليس أنها وصلت إلى صندوق الوارد. الرمز 403 قد يشير إلى نطاق صلاحية مفقود أو نطاق غير مُتحقَّق منه. الرمز 422 يحجب مستلمًا موقوفًا. الرمز 429 يشير إلى تجاوز حد المعدل.

حدود الخدمة الحالية

ترفض REST API المرفقات. تقبل فقط الرؤوس المخصصة In-Reply-To وReferences وList-Unsubscribe وList-Unsubscribe-Post (حتى 8). البريد المستضاف منفصل: عميل الويب يدعم 20 مرفقًا بإجمالي 25 MiB؛ عميل سطح المكتب المنشور يحد الإرسال بـ10 MiB. يعني HTTP 202 وemail.accepted القبول للمعالجة؛ قبول SMTP لا يضمن التسليم أو الوصول إلى الوارد.

نموذج الوصول الحالي

تستخدم المفاتيح الحالية srs_live_. قبل التحقق من نطاق From لا يرسل مرسل sandbox المشترك إلا إلى أعضاء المشروع. بعد ذلك تطبق الحصص وقائمة suppression وحدود المستلمين وضوابط إساءة الاستخدام. تعني 202 وضع الرسالة في الطابور لا تسليمها.

موارد التكامل

استخدم الدليل العملي للبشر ووكلاء الذكاء الاصطناعي، واعتبر OpenAPI مصدر الحقيقة للحقول.