API

الإرسال بقالب

المتن المخزَّن يوفّر الرسالة؛ والطلب يوفّر الظرف والقيم.

POSTapi.openemail.uk/templates/{id}/send

ينفّذ الاستدعاء الحقيقي على مساحة عملك، بمفتاحك أنت.

POST /templates/{id}/send

المتن المخزَّن يوفّر الرسالة؛ والطلب يوفّر الظرف والقيم.

مثال

يتطلب templates:write وemails:send معاً. ويحترم Idempotency-Key تماماً كما يفعل POST /emails.

curl

curl -X POST "$OE/templates/order-shipped/send" -H "$AUTH" \  -H "Content-Type: application/json" -H "Idempotency-Key: order:AC-4192:shipped" \  -d '{    "from": "Acme Dispatch <[email protected]>",    "to": ["[email protected]"],    "version": 5,    "props": { "orderId": "AC-4192", "customer": "Ada" }  }'

الاستجابة

{  "object": "email",  "id": "msg_c5f21cc6…",  "status": "queued",  "from": "[email protected]",  "subject": "Order AC-4192 is on its way",  "template": { "id": "order-shipped", "version": 5 }}

كلا النطاقين، ولا فائض فيهما: templates:write لأن المستدعي يصل إلى متن مخزَّن، وemails:send لأن البريد يغادر مساحة العمل. فالمفتاح الذي يجوز له إرسال متونه الخاصة لا يستطيع مع ذلك إرسال قالب شخص آخر.

ثبّت version في أي عملية مؤتمتة. فإن أغفلته حللت ما يكون منشوراً في تلك اللحظة، وهو ما تريده حين يملك غيرك النص، وليس ما تريده صباح اليوم الذي يعيد فيه كتابته.

يتجاوز subject موضوع القالب لهذه الرسالة وحدها، ويتصرف cancellableForSeconds وtracking وtags تماماً كما تتصرف في إرسال عادي.

يقبل POST /emails حقل template يؤدي الغرض نفسه، لمستدعٍ يبني رسائله هناك أصلاً. وتوجد نقطة النهاية هذه حتى لا يستلزم الوصول إلى متن مخزَّن تقديم بنية رسالة لست أنت من يؤلّفها.

متى يُرفض الإرسال

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

الرمز	الحالة	ما الذي حدث
`resource_not_found`	404	لا قالب على هذا الاتصال بذلك المعرّف أو الـ slug.
`template_not_published`	422	موجود ولم يُنشر قط، أو الإصدار الذي سمّيته ما زال مسوّدة.
`template_version_not_found`	422	ثبّتّ قيمة `version` لم يملكها هذا القالب قط.
`missing_template_prop`	422	خاصية معلَنة `required` كانت غائبة أو null أو فارغة.
`unknown_template_prop`	422	مرّرت مفتاحاً لا يعلنه الإصدار. والرسالة تسمّي المفاتيح التي يعلنها.
`unknown_template_slot`	422	الشيء نفسه، لكن لفتحة.
`invalid_template_prop`	422	قيمة ليست string ولا number ولا boolean. فالـ object أو الـ array لا يمكن استبداله داخل HTML.

قيمة param في هذه الأخطاء هي template.props.<key>، فيستطيع العميل الإشارة إلى الحقل الذي أخطأ فيه دون تحليل نص الرسالة.