Creating email templates
A template is a stored subject, HTML body and text body, any of which may
contain {{variable}} placeholders. It belongs to your workspace, not to a
mailbox or a domain, and any key with the right scope can send with it.
Create one
curl -X POST https://api.lockally.com/v1/templates \
-H "Authorization: Bearer $LOCKALLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Order receipt",
"subject": "Your order {{order_id}}",
"html": "<p>Thanks {{first_name}}, we have your order.</p>",
"text": "Thanks {{first_name}}, we have your order."
}'
{
"id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
"name": "Order receipt",
"subject": "Your order {{order_id}}",
"html": "<p>Thanks {{first_name}}, we have your order.</p>",
"text": "Thanks {{first_name}}, we have your order.",
"created_at": "2026-10-20T09:14:22Z",
"updated_at": "2026-10-20T09:14:22Z"
}
The id is what you pass to /v1/send. See Template IDs.
The fields
| Field | Required | Notes |
|---|---|---|
name |
yes | 1 to 120 characters. For you, never shown to a recipient. |
subject |
no | Up to 255 characters. May contain placeholders. |
html |
no | Up to 512 KiB. Placeholder values are HTML-escaped. |
text |
no | Up to 512 KiB. Placeholder values are not escaped. |
At least one of html or text is required. A template with neither is
rejected with Supply at least one of 'html' or 'text'.
subject is optional at the template level, which means a template can store a
body and no subject. The send then goes out with an empty subject rather than
failing, so treat the subject as required in practice unless you have a reason
not to.
Names are not unique
Nothing stops two templates sharing a name. The list endpoint orders by name, so duplicates sit next to each other and are told apart only by their ids. If you look templates up by name in your own code, handle more than one match.
Scopes
| Action | Scope |
|---|---|
GET /v1/templates, GET /v1/templates/{id} |
templates:read |
POST, PUT, DELETE /v1/templates/{id} |
templates:write |
Sending with template_id |
send:write only |
That last row is worth reading twice. Sending with a template does not
require templates:read. The send endpoint loads the template internally,
scoped to your workspace, without a separate permission check. A key that only
sends needs send:write and nothing else.
From the console
Templates in the left-hand navigation lists what exists, and New template opens an editor with a live preview beside the fields. The editor detects placeholders as you type and offers a box for each so you can see the message filled in. See Previewing templates.
Templates are available on every plan. There is no tier that withholds them.
Updating and deleting
PUT /v1/templates/{id} replaces the template. It is not a patch: every field
you leave out is written as empty. DELETE /v1/templates/{id} returns 204 and
is immediate.
An edit is recoverable: every save is kept and can be restored. A delete is not, and takes the history with it. See Template versions.