التوثيق

ابدأ مع Postline بأمان

التحقق من النطاق، الوصول إلى API، الإرسال التجريبي (sandbox)، قوائم الإيقاف، وأحداث التسليم.

آخر تحديث: 24 يوليو 2026فتح مرجع API

قائمة التحقق قبل الإنتاج

تحقق من ملكية نطاق From.
انشر سجل DKIM المُصدَر لك ورخّص بنية return-path من خلال SPF.
اضبط محاذاة DMARC وراجع النتيجة قبل تفعيل الإرسال في بيئة الإنتاج.
استخدم مفتاح اختبار محدود النطاق في sandbox ومفتاحًا منفصلاً للإنتاج (live).
عالج webhooks الارتداد (bounce) والشكاوى (complaint) بشكل متكرر الأمان (idempotent) والتزم بقرارات الإيقاف (suppression).

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"
}

مصطلحات المصادقة

توقّع Postline الرسائل بواسطة DKIM. أما SPF فهو سياسة تفويض تُنشر في DNS. يقيّم DMARC المحاذاة بين نطاق From الظاهر وهوية مصادَق عليها عبر SPF أو DKIM؛ ولا يُستخدم SPF أو DMARC كتوقيع للرسالة.

يحمي TLS البيانات أثناء النقل بين المحطات الداعمة له. البريد الإلكتروني العادي غير مشفّر من طرف إلى طرف، ويمكن لمزوّد المستلم معالجة محتوى الرسالة.

نتائج التسليم

قبول خادم المستلم للرسالة لا يثبت وصولها إلى صندوق الوارد. تعامل مع الحالات accepted وdeferred وhard bounce وsoft bounce وcomplaint وsuppressed وspam placement وinbox placement كنتائج مختلفة.

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

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

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

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