Skip to main content
A template holds an email’s subject, HTML and text, with placeholders such as {{customer_name}}. Your app sends it with its own values through send-template. Use one for any email you send often: welcome emails, password resets, order confirmations. These templates have no editor in the dashboard. Manage them through the API, or ask your AI assistant to list, create, change or delete them. Marketing campaigns use their own templates: see Email Marketing templates.

​
Create a template

POST /api/v1/email/templates creates one. The key needs the Manage Templates permission.
​
string
required
A name unique in your account. send-template can pick the template by it. A name already in use answers 409 duplicate_name.
​
string
required
The subject line. It may hold placeholders.
​
string
The HTML body. Send html, text, or both.
​
string
The plain-text body. Without one, a send makes the text from the HTML.
​
string
The default sender, used when a send names none: "Acme Orders <orders@mail.acme.com>" or a bare address.
​
string[]
The default Reply-To addresses.
​
array
The placeholders, each { "name": "...", "required": true }. Leave it out and Hiveku lists every placeholder it finds, none of them required.
​
string
A note for your team. It is never sent.

​
Placeholders

  • {{customer_name}} takes the value named customer_name.
  • {{order.number}} reads into nested values: { "order": { "number": "1024" } }.
  • A placeholder with no value is left in the email as it is.
  • A send that leaves out a required variable is refused with 400 missing_variables, which names them in missing. The check looks at top-level names only: to require {{order.number}}, mark order as required.
  • Values go in as text. A variable can also carry a type or a default, but Hiveku does not use them when it fills the template.
In the HTML body, each value is HTML-escaped, so text your users typed shows as text. Write {{{name}}} (three braces) to insert a value as HTML, as it is. The subject and the plain text get values as typed. A template that passes HTML through a variable today must switch that placeholder to {{{name}}}.

​
List, read, change and delete

Each template also shows times_used and last_used_at. "active": false switches a template off without deleting it. A send that names a switched-off template answers 404 not_found. Your AI assistant deletes a template the same way when you ask it to.

​
Versions

A template has a version number. It starts at 1 and goes up by one each time the subject, HTML or text changes. Hiveku keeps no copy of earlier versions: every send uses the template as it is now. To change a template that live code depends on, such as renaming a variable, create a new template and move your sends over to it.

​
Send with a template

from, subject and reply_to in the request override the template’s defaults. See Send with a template for the other fields and the answer.