Template validation
Saving a template runs four checks. Knowing which four matters mainly because of how much is left out.
What is checked
POST /v1/templates and PUT /v1/templates/{id} both validate the same way.
Leading and trailing whitespace is trimmed from name and subject first.
| Check | Failure detail |
|---|---|
name is present after trimming |
A template needs a name. |
name is at most 120 characters |
That template name is too long. |
subject is at most 255 characters |
That subject is too long. |
html and text are each at most 512 KiB |
That template is too large to save. |
at least one of html or text is non-empty |
Supply at least one of `html` or `text`. |
every {{ forms a valid placeholder |
names the offending text, see below |
All of them return 400 with the title Invalid template. The first failure
in that order is the one you are told about, so fixing one can reveal another.
Malformed placeholders are rejected
Braces that do not form a placeholder are refused at save time, in all three fields:
{
"status": 400,
"title": "Invalid template",
"detail": "The text contains \"{{first name}}\", which is not a placeholder and would be sent to the recipient as written. A placeholder is {{name}}, where the name holds only letters, digits, underscores, dots or hyphens. There are no conditionals, loops or default values."
}
That covers a space inside the name, handlebars syntax such as {{#if x}},
empty braces, and an unclosed {{. The renderer itself stays permissive and
passes anything it does not recognise straight through, which is correct when
a message is being sent and useless when one is being written: saving is the
only moment the mistake is cheap to catch.
A single brace is untouched, so { like this } saves fine.
What is not checked
This is the longer list, and every item on it is a way to save a template that is broken.
Variable names are not checked against anything. The braces must be
well-formed, but the name inside them can be anything legal. There is no
declared set of variables for a template, so a typo in a name is
indistinguishable from a deliberate placeholder. {{frist_name}} is a valid
placeholder; it is just one nothing will ever fill.
The HTML is not parsed. Unclosed tags, a stray <, a broken entity: all
stored and all sent. The body is treated as opaque text.
The subject is not checked for control characters. A newline in a stored subject, or in a value substituted into it, is accepted.
Nothing checks that the template renders sensibly. A template whose body is
only {{body}} is valid.
There is no dry-run endpoint
Nothing exposes “check this template without saving it”. Saving is the validation step, and there is no way to ask the question without committing the answer.
What you do not have to do yourself any more is work out what a template
needs: the resource carries a
variables array.
To know what a template renders, render it. The console does this live while you edit, and a test-key send does it server-side. See Previewing templates and Testing rendered emails.
A validation step worth writing yourself
If templates are edited by people who are not the people who call the API, the
check worth having in your own test suite is the one nothing here can do for
you: for each template id your code sends, assert that the template’s
variables array equals the set of keys your code supplies.
That catches both halves of the silent-failure pair in
Template variables: a placeholder nobody fills, and a
variable nobody uses. Neither is an error at save time or at send time, and
the variables array is what makes the assertion a one-liner.