Create and reuse email templates
Write a template once, fill it with variables at send time, and keep a version history you can roll back.
NevarMail templates let you create reusable email content with variable placeholders. Templates support versioning, validation, and preview rendering.
All /api/templates* endpoints on this page require a signed-in browser session -- API keys get a 403 SESSION_ONLY error. They return the object itself, with no envelope; the list is the one exception, returning { data, pagination } (see List templates). The API-key surface is /api/v1/templates/* (see API-key access below), which uses the standard {data, requestId} v1 envelope and has additional endpoints not covered by the session routes below.
Create a template
POST /api/templates
{
"name": "Welcome Email",
"subject": "Welcome, {{user.name}}!",
"htmlTemplate": "<h1>Hello {{user.name}}</h1><p>Welcome to {{company.name}}.</p>",
"textTemplate": "Hello {{user.name}}. Welcome to {{company.name}}.",
"variables": [
{ "name": "user.name", "type": "string", "required": true },
{ "name": "company.name", "type": "string", "required": true }
],
"category": "onboarding",
"projectId": "6f1c2a1e-8a4b-4f0e-9d3c-2b7e5a9c1d40"
}A template you create belongs to one project, and shows only in that project's template list. Creating one from a project's Template Studio puts it in that project. Through this API, projectId names the project: one you can open, or 404. Leave it out and the template goes to your organization's only project; with more than one project, leaving it out is 400 PROJECT_REQUIRED, and with none it is 422 NO_PROJECT. (Templates imported from your provider that match no single project stay organization-wide and show in every project, marked "No project".)
Template fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Template name |
subject | string | Yes | Subject line (supports {{variables}}) |
htmlTemplate | string | One of the two | HTML body (supports {{variables}}) |
textTemplate | string | One of the two | Plain text body (supports {{variables}}) |
variables | array | No | Variable declarations |
category | string | No | Template category for organization |
projectId | string | When you have more than one project | The project the template belongs to |
A template needs at least one body. A request with neither htmlTemplate nor textTemplate is rejected with 400 VALIDATION_ERROR, because a template with no body cannot be sent.
Variable declarations
Each variable in the variables array has:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The placeholder's key, exactly as written between the braces (e.g., user.name) |
type | string | Yes | Variable type (string, number, etc.) |
required | boolean | No | Shows an asterisk beside the field in the in-app compose form. Nothing enforces it |
default | string | No | Value the in-app compose form pre-fills |
Declarations describe the template; they do not change how it renders. Render and send through the API do not enforce required or apply default: a variable you leave out is sent as written (see Variable syntax). The in-app compose form is different: it sends every declared variable, so a field left blank is sent as an empty string. Validate compares the declarations with the placeholders the template uses.
List templates
GET /api/templatesQuery parameters
| Parameter | Type | Description |
|---|---|---|
category | string | Filter by category |
isActive | string | "true" or "false" to filter by status |
search | string | Search templates by name |
projectId | string | That project's templates plus the org-wide ones |
page | number | Page number, from 1 (default 1) |
limit | number | Templates per page, 1-100 (default 25) |
The list is paginated, so unlike the other session routes it wraps its results:
{
"data": [{ "id": "...", "name": "Welcome Email", "version": 2 }],
"pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1 }
}Get a template
GET /api/templates/:idUpdate a template
PUT /api/templates/:id
{
"subject": "Welcome aboard, {{user.name}}!",
"htmlTemplate": "<h1>Welcome aboard, {{user.name}}</h1>"
}Send only the fields you are changing; fields you leave out keep their current value. Every field you send counts as a change, even if its value is the same as before: the update increments the template version number and adds a revision. Only an empty body ({}) leaves version unchanged.
Delete a template
DELETE /api/templates/:idReturns { "deleted": true } on success.
Validate a template
Check a template for variable declaration mismatches before sending. There is no API-key equivalent.
POST /api/templates/:id/validate{
"valid": true,
"errors": [],
"warnings": ["Variable \"foo\" is declared but never used in template"],
"variables": ["user.name", "company.name"]
}- Errors: A
{{variable}}is used in the template but not declared - Warnings: A variable is declared but never referenced in the template
Render a template
Preview a template with variable values without sending an email. The session route takes the values wrapped in variables:
POST /api/templates/:id/render
{
"variables": {
"user.name": "Jane",
"company.name": "Acme"
}
}{
"html": "<h1>Hello Jane</h1><p>Welcome to Acme.</p>",
"text": "Hello Jane. Welcome to Acme.",
"subject": "Welcome, Jane!"
}The API-key route, POST /api/v1/templates/:id/render, takes the variables object as the request body itself -- see Render with an API key.
API-key access
API keys use a separate route tree, /api/v1/templates/*, scoped to templates:read / templates:write. Every response uses the v1 envelope { "data": ..., "requestId": "..." } (list endpoints also add pagination), unlike the session routes above.
| Method | Path | Description |
|---|---|---|
GET | /api/v1/templates | Paginated list (page, perPage query params) |
POST | /api/v1/templates | Create a template |
GET | /api/v1/templates/:id | Get a template |
PATCH | /api/v1/templates/:id | Partial update |
DELETE | /api/v1/templates/:id | Delete a template |
POST | /api/v1/templates/:id/render | Render with variables, without sending (templates:read). The body is the variables object itself |
GET | /api/v1/templates/:id/versions | Revision history, newest first -- every create, edit, provider import, or restore appends one entry |
POST | /api/v1/templates/:id/versions/:version/restore | Roll back to an earlier revision. The rollback is written forward as a new revision, so history stays append-only |
POST | /api/v1/templates/import | Adopt templates that already exist at the org's connected provider. Idempotent -- re-running refreshes content on already-imported templates |
Render with an API key
Send the variables as the whole request body. Do not wrap them in { "variables": ... }: the v1 route would read variables as the name of a single variable, and every placeholder would stay as written.
POST /api/v1/templates/:id/render
{
"user.name": "Jane",
"company.name": "Acme"
}{
"data": {
"html": "<h1>Hello Jane</h1><p>Welcome to Acme.</p>",
"text": "Hello Jane. Welcome to Acme.",
"subject": "Welcome, Jane!"
},
"requestId": "req_..."
}Variable syntax
Templates use double-brace placeholders: {{name}}, and triple-brace placeholders for HTML: {{{name}}}. Spaces inside the braces are ignored, so {{ name }} and {{name}} are the same placeholder. The same rules apply when you render and when you send. Placeholders are read the same way in the subject, the HTML body and the text body. How a value is written depends on the part (see the escaping rules below).
- Keys are flat. Everything between the braces is the key, dots included:
{{user.name}}reads the variable nameduser.name, so pass{ "user.name": "Jane" }. A nested object such as{ "user": { "name": "Jane" } }does not fill it. - Missing values are sent as written. A placeholder with no matching variable, or one whose value is
null, stays in the output as a placeholder, written without any spaces:{{ user.name }}comes out as{{user.name}}. Render the template first to catch these before a recipient sees them. {{name}}is HTML-escaped in the HTML body.&,<,>,"and'in the value are written as HTML entities, so a value someone typed shows as typed and cannot add markup. Pass plain values: escaping them yourself escapes them twice. An object or array value is inserted as JSON, escaped the same way.{{{name}}}inserts the value as written. Use it for HTML your own code built. NevarMail does not clean that HTML, so escape anything a person typed before you put it inside.- The text body and the subject are not escaped. The text body gets the value as you pass it. In the subject, line breaks in a value are replaced by spaces, so a value cannot add a line to the subject.
- No logic blocks. A placeholder is only ever replaced by a value. Handlebars blocks and helpers such as
{{#if}},{{#each}}and{{else}}are not evaluated: each is treated as a key, finds no value, and is sent as written.
Templates adopted with import keep the content they had at the provider, including any provider syntax such as SendGrid's Handlebars blocks and nested paths. Rewrite them to flat {{key}} placeholders (or {{{key}}} for a value that is HTML), and render them, before you send with them through NevarMail.
See Sending Email for how to send templated emails with variable values, and Send each subscriber their own version of an email for worked examples.
Send a transactional email
Send a one-off email, send from a template, or schedule one for later — with the request and response shapes you will actually get back.
Send each subscriber their own version of an email
Fill one template with each recipient's own data at send time, such as a personal offer or a newsletter written for the reader, under a use case your subscribers can unsubscribe from.