Send with a template
The stored body supplies the message; the request supplies the envelope and the values.
Runs the real call against your workspace, with your own key.
POST /templates/{id}/send
The stored body supplies the message; the request supplies the envelope and the values.
Example
Needs templates:write AND emails:send. Honours Idempotency-Key exactly as POST /emails does.
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 }}Both scopes, and neither is redundant: templates:write because the caller is reaching a stored body, emails:send because mail leaves the workspace. A key that may send its own bodies still cannot send somebody else’s template.
Pin version in anything automated. Omitted, you resolve whatever is published at that moment, which is what you want when somebody else owns the copy and not what you want the morning they rewrite it.
subject overrides the template’s own for this message only, and cancellableForSeconds, tracking and tags behave exactly as they do on a plain send.
POST /emails accepts a template field that does the same thing, for a caller that already builds messages there. This endpoint exists so that reaching a stored body does not require supplying the shape of a message you are not composing.
When a send is refused
Props are a contract rather than a suggestion, and every failure below happens before anything is dispatched. The alternative, a message going out with a blank where the order number was, is not reported by anything and cannot be recalled.
| Code | Status | What happened |
|---|---|---|
| `resource_not_found` | 404 | No template on this connection with that id or slug. |
| `template_not_published` | 422 | It exists and has never been published, or the version you named is still a draft. |
| `template_version_not_found` | 422 | You pinned a version this template has never had. |
| `missing_template_prop` | 422 | A prop declared required was absent, null or empty. |
| `unknown_template_prop` | 422 | You passed a key the version does not declare. The message names the ones it does. |
| `unknown_template_slot` | 422 | The same, for a slot. |
| `invalid_template_prop` | 422 | A value that is not a string, a number or a boolean. An object or an array cannot be substituted into HTML. |
param on these is template.props.<key>, so a client can point at the field it got wrong without parsing the message.