Template errors
All errors are problem documents. The tables
below give the title and detail you will see.
Managing templates
POST /v1/templates, PUT /v1/templates/{id}, GET, DELETE.
| Status | Title | Detail | Cause |
|---|---|---|---|
| 400 | Invalid JSON body |
the decoder’s message | Malformed JSON, or a field of the wrong type. |
| 400 | Invalid template |
A template needs a name. |
name missing or whitespace only. |
| 400 | Invalid template |
That template name is too long. |
Over 120 characters. |
| 400 | Invalid template |
That subject is too long. |
Over 255 characters. |
| 400 | Invalid template |
That template is too large to save. |
html or text over 512 KiB. |
| 400 | Invalid template |
Supply at least one of `html` or `text`. |
Both empty. |
| 400 | Invalid template |
names the offending text | A {{ that does not form a placeholder. |
| 400 | Invalid template id |
empty | The path segment is not a UUID. |
| 404 | Template not found |
empty | No such template in this workspace. |
| 403 | Insufficient scope |
This endpoint requires scope: templates:write |
Key lacks templates:read or templates:write. Carries "code": "insufficient_scope". |
Validation stops at the first failure in the order above, so correcting one can reveal the next.
Template history
GET /v1/templates/{id}/versions, GET .../versions/{version},
POST .../versions/{version}/restore.
| Status | Title | Detail | Cause |
|---|---|---|---|
| 400 | Invalid template id |
empty | The id is not a UUID. |
| 400 | Invalid version |
names what a version is | Not a positive whole number. |
| 404 | Template not found |
empty | No such template in this workspace. |
| 404 | Version not found |
No version N for that template. |
Never existed, or pruned past the 50-version cap. |
| 403 | Insufficient scope |
names the scope | Restoring needs templates:write; reading needs templates:read. |
Sending with a template
POST /v1/send and each entry of POST /v1/send/batch.
| Status | Title | Detail | Cause |
|---|---|---|---|
| 400 | Template conflict |
Provide either template_id or inline subject/text/html, not both. |
template_id sent with any of subject, html, text. |
| 400 | Invalid template_id |
empty | Not a UUID. |
| 400 | Template not found |
No template with that id. |
Well-formed UUID, no such template here. |
| 400 | Invalid variables |
Template variables must be strings... |
A number, boolean, array or object in variables. |
| 400 | Invalid JSON body |
names the field and the type it wanted | A type error on some other field. |
In a batch these arrive as the error string on the individual result rather
than as a problem document, keyed by index. One bad entry does not fail the
others.
The non-string variable error
{ "variables": { "order_total": 49.99 } }
{
"status": 400,
"title": "Invalid variables",
"detail": "Template variables must be strings. Quote every value, including numbers and booleans: {\"variables\": {\"total\": \"49.99\"}}, not {\"variables\": {\"total\": 49.99}}."
}
Nothing is wrong with your JSON as JSON. variables accepts strings only, and
a number, boolean, array or object in any value rejects the whole request
before anything else is looked at.
null is accepted and renders as an empty string.
Errors you will not get
These are the cases people expect to be errors and which succeed instead. Each one is covered in more detail elsewhere, and together they are the reason to read a rendered message rather than a status code.
| What you did | What happens |
|---|---|
| Misspelt a placeholder in the template | Renders as an empty string. 202. |
Misspelt a key in variables |
Ignored. 202. |
| Omitted a variable the template uses | Renders as an empty string. 202. |
| Saved a template with broken HTML | Stored and sent as written. |
| Saved a template with no subject | Sent with an empty subject. |
{{#if x}} and {{a b}} used to be on that list too, sent to the recipient
as literal text. They are now rejected at save time: see
Template validation.
The rest remain, because none of them can be distinguished from something somebody meant. Testing rendered emails is how to catch them.