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>, так что клиент может указать на поле, в котором ошибся, не разбирая текст сообщения.