NevarMail

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

FieldTypeRequiredDescription
namestringYesTemplate name
subjectstringYesSubject line (supports {{variables}})
htmlTemplatestringOne of the twoHTML body (supports {{variables}})
textTemplatestringOne of the twoPlain text body (supports {{variables}})
variablesarrayNoVariable declarations
categorystringNoTemplate category for organization
projectIdstringWhen you have more than one projectThe 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:

FieldTypeRequiredDescription
namestringYesThe placeholder's key, exactly as written between the braces (e.g., user.name)
typestringYesVariable type (string, number, etc.)
requiredbooleanNoShows an asterisk beside the field in the in-app compose form. Nothing enforces it
defaultstringNoValue 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/templates

Query parameters

ParameterTypeDescription
categorystringFilter by category
isActivestring"true" or "false" to filter by status
searchstringSearch templates by name
projectIdstringThat project's templates plus the org-wide ones
pagenumberPage number, from 1 (default 1)
limitnumberTemplates 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/:id

Update 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/:id

Returns { "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.

MethodPathDescription
GET/api/v1/templatesPaginated list (page, perPage query params)
POST/api/v1/templatesCreate a template
GET/api/v1/templates/:idGet a template
PATCH/api/v1/templates/:idPartial update
DELETE/api/v1/templates/:idDelete a template
POST/api/v1/templates/:id/renderRender with variables, without sending (templates:read). The body is the variables object itself
GET/api/v1/templates/:id/versionsRevision history, newest first -- every create, edit, provider import, or restore appends one entry
POST/api/v1/templates/:id/versions/:version/restoreRoll back to an earlier revision. The rollback is written forward as a new revision, so history stays append-only
POST/api/v1/templates/importAdopt 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 named user.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.

On this page