Enviar com um modelo
O corpo guardado fornece a mensagem; o pedido fornece o envelope e os valores.
Executa a chamada real contra o seu espaço de trabalho, com a sua própria chave.
POST /templates/{id}/send
O corpo guardado fornece a mensagem; o pedido fornece o envelope e os valores.
Exemplo
Requer templates:write E emails:send. Respeita Idempotency-Key exatamente como POST /emails.
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 }}Os dois âmbitos, e nenhum é redundante: templates:write porque quem chama está a aceder a um corpo guardado, emails:send porque o correio sai do espaço de trabalho. Uma chave que pode enviar os seus próprios corpos continua a não poder enviar o modelo de outra pessoa.
Fixe version em tudo o que seja automatizado. Se a omitir, resolve o que estiver publicado nesse momento, o que é o que quer quando outra pessoa é responsável pelo texto, e não o que quer na manhã em que essa pessoa o reescreve.
subject substitui o assunto do próprio modelo apenas nesta mensagem, e cancellableForSeconds, tracking e tags comportam-se exatamente como num envio simples.
POST /emails aceita um campo template que faz o mesmo, para quem já constrói mensagens aí. Este endpoint existe para que aceder a um corpo guardado não obrigue a fornecer a estrutura de uma mensagem que não está a compor.
Quando um envio é recusado
As props são um contrato e não uma sugestão, e todas as falhas abaixo acontecem antes de qualquer envio. A alternativa, uma mensagem a sair com um espaço em branco onde estava o número da encomenda, não é reportada por nada e não pode ser recolhida.
| Código | Estado | O que aconteceu |
|---|---|---|
| `resource_not_found` | 404 | Não há nenhum modelo nesta ligação com esse id ou slug. |
| `template_not_published` | 422 | Existe e nunca foi publicado, ou a versão que indicou ainda é um rascunho. |
| `template_version_not_found` | 422 | Fixou uma version que este modelo nunca teve. |
| `missing_template_prop` | 422 | Uma prop declarada required estava ausente, a null ou vazia. |
| `unknown_template_prop` | 422 | Passou uma chave que a versão não declara. A mensagem indica as que declara. |
| `unknown_template_slot` | 422 | O mesmo, para um slot. |
| `invalid_template_prop` | 422 | Um valor que não é string, number nem boolean. Um object ou um array não pode ser substituído em HTML. |
Nestes erros, param é template.props.<key>, para que um cliente possa apontar o campo que errou sem analisar a mensagem.