تكامل الذكاء الاصطناعي

ربط إرسال البريد الإلكتروني بوكلاء الذكاء الاصطناعي

مسار قابل للقراءة الآلية لوكلاء البرمجة والمساعدين الذين يحتاجون إلى إضافة بريد إلكتروني معاملاتي إلى مشروع شخص آخر — ماذا تستدعي، وبأي ترتيب، وأي فحوصات يجب تشغيلها قبل كل عملية إرسال.

تنزيل OpenAPI 3.1

قبل كتابة أي كود

  • اطلب من المستخدم مفتاح API للمشروع، أو اطلب منه إنشاء مفتاح sandbox عبر https://app.srs-postline.com/ar/login — لا تخترع مفتاحًا أو تخمّنه أو تعيد استخدام مفتاح من مشروع آخر أبدًا.
  • ضع المفتاح في متغيّر بيئة على جانب الخادم. لا تضعه في كود الواجهة الأمامية، أو حزمة تطبيق جوال، أو مستودع عام، أو ملف .env تم الالتزام به (committed).
  • اقرأ /llms.txt وopenapi/postline.yaml قبل توليد كود الطلبات؛ ولا تخمّن أسماء الحقول أو نقاط النهاية.

إرسال بسيط

POST /v1/emails
Authorization: Bearer srs_live_...
Idempotency-Key: <stable-id-per-logical-send>
Content-Type: application/json

{
  "from": "Sender Name <info@example.com>",
  "to": ["user@example.net"],
  "subject": "الموضوع",
  "html": "<p>النص</p>",
  "text": "النص"
}

فحوصات يجب تشغيلها قبل كل إرسال

  • أرسل دائمًا مفتاح Idempotency-Key مُشتقًا من الإجراء المُحفِّز (معرّف الطلب، معرّف الحدث) بحيث لا تتسبب إعادة المحاولة في إرسال مضاعف.
  • لا تضع رموز OTP أو رموز إعادة تعيين كلمة المرور أو أي أسرار أخرى في حقل يُسجَّل أو يُعاد توجيهه خارج نص الرسالة.
  • اطلب أضيق نطاق صلاحية (scope) لمفتاح API تحتاجه المهمة (يكفي emails:send للإرسال؛ لا تطلب domains:write أو api_keys:write إلا إذا تطلبت المهمة ذلك).
  • حدّد عدد المستلمين بـ100 لكل استدعاء. لا تقبل الواجهة الحالية المرفقات أو الترويسات المخصصة؛ ارفض الملف أو شارك رابطًا دون الادعاء بأنه أُرفق.
  • لا تُعِد المحاولة بصمت عند استجابات 4xx. الرمزان 429 و503 فقط آمنان لإعادة المحاولة، وبتأخير تصاعدي (backoff) فقط.

تعامل مع كل رمز استجابة

  • 202 — أُدرجت في قائمة الانتظار، لم تُسلَّم بعد. احفظ المعرّف (id) المُعاد إذا احتجت للاستعلام عن الحالة لاحقًا.
  • 400 — حمولة (payload) غير صالحة؛ صحّح الطلب، ولا تُعِد إرساله كما هو.
  • 401 — مفتاح غير صالح أو منتهي الصلاحية؛ توقّف وأبلغ المستخدم بذلك، ولا تختلق مفتاحًا جديدًا.
  • 403 — نطاق صلاحية مفقود أو نطاق الإرسال لم يُتحقَّق منه بعد؛ أخبر المستخدم بضرورة التحقق من النطاق قبل المتابعة.
  • 422 — المستلم موقوف (بسبب ارتداد أو شكوى سابقة)؛ لا تُعِد المحاولة مع هذا المستلم.
  • 429 — تم تجاوز حد المعدل؛ تراجع وأعد المحاولة لاحقًا، ولا تدخل في حلقة محاولات متلاحقة.
  • 503 — قائمة الانتظار غير متاحة؛ أعد المحاولة بتأخير تصاعدي، ولا تلجأ إلى وسيلة نقل غير رسمية.

إذا كانت المهمة تتضمن استقبال الأحداث

سجّل نقطة نهاية webhook عبر HTTPS فقط. أعِد حساب التوقيع بنفسك قبل الوثوق بأي حمولة (payload)؛ ولا تتخطَّ التحقق لمجرد أن الطلب «يبدو داخليًا».

signature = HMAC-SHA256(webhook_secret, timestamp + "\0" + event_id + "\0" + raw_body)

قارن مع رأس Postline-Signature (مقارنة بزمن ثابت / constant-time compare)
ارفض الطلب إذا كان Postline-Timestamp خارج النافذة الزمنية المسموح بها
احفظ event_id وعالج كل حدث مرة واحدة بالضبط

مراجع قابلة للقراءة الآلية

  • /llms.txt — فهرس مُختصر لهذه القواعد لنوافذ سياق الوكلاء.
  • /openapi/postline.yaml — مخطط OpenAPI 3.1 الكامل لكل نقطة نهاية.
  • /ar/api/ — مرجع API للقراءة البشرية.
  • /ar/webhooks/ — تفاصيل توقيع webhook وإعادة المحاولة.

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

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

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

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