Template IDs
A template id is a UUID. It is the only handle the send API accepts: there is no way to send by template name.
{
"from": "receipts@yourcompany.com",
"to": ["alice@example.com"],
"template_id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
"variables": { "first_name": "Alice", "order_id": "12345" }
}
Where it comes from
The id in the response to POST /v1/templates, or from GET /v1/templates.
In the console, open a template and it is the last path segment of the URL.
It is stable for the life of the template
The id is assigned at creation and never changes. Editing a template with
PUT /v1/templates/{id} keeps the same id, which is what makes it safe to hard-code
in your application: change the wording in the console and the next send picks
it up without a deploy.
That is also the hazard. Because the id survives an edit, a hard-coded id keeps working while sending different content, and there is no way to pin a send to a particular version. What you do get is a record: every save is kept and can be restored. See Template versions.
Deleting a template destroys the id. Creating a replacement with the same name produces a new one, and anything still sending the old id starts failing.
Scoped to your workspace
A template id is only meaningful inside the workspace that owns it. Another workspace’s id is not an error you can distinguish from a typo: both answer “no template with that id”. You cannot read, send with, or probe for a template belonging to anyone else.
Live and test keys for the same workspace see the same templates. There is no separate test template store.
When the id is wrong
Two different failures, both 400, both from /v1/send:
{
"status": 400,
"title": "Invalid template_id",
"detail": ""
}
The string is not a UUID at all. Check for a stray quote, a truncated value, or a template name passed where an id belongs.
{
"status": 400,
"title": "Template not found",
"detail": "No template with that id."
}
Well-formed UUID, no such template in this workspace. Either it was deleted, or the id belongs to somewhere else.
See Template errors for the full set.