Create a template

POST/v1/templatesAPI key

Creates version 1 of a template stored in the project. Send it with template: "<name>" in Send an email. The syntax ({{name}}, {{{raw}}}, {{#if}}, {{#each}}) is described in Custom templates.

You can reuse the name of a built-in template. The stored template then wins over the built-in one for this project.

Body parameters

namestringrequired

1 to 100 characters: lowercase letters, digits, - and _, starting with a letter or digit. Must be unique in the project.

subjectstringrequired

1 to 998 characters. Variables are allowed, for example Welcome, {{first_name}}. Not HTML-escaped.

htmlstringrequired

The HTML body. Values inserted with {{…}} are HTML-escaped; {{{…}}} inserts them as is.

textstring

The plain text body. When you leave it out, sends get a text version made from the rendered HTML.

variablesVariable[]

The variables the template expects. A required variable must be present and not empty in data, or the send fails with 400 invalid_template_data.

Show variable properties

namestringrequired

The variable path, for example first_name or order.total.

requiredbooleandefault: false

Reject sends that don't provide it.

exampleany

An example value. Stored with the template and returned as is.

Response

Status 201.

idstring

The template ID, for example tmpl_01K6B5A7C9E1G3J5L7N9Q1S3U5.

source'db'

Always db for stored templates.

projectIdstring

The project the template belongs to.

namestring

The template name.

subjectstring

The subject, unrendered.

htmlstring

The HTML, unrendered.

textstring | null

The text body, or null.

variablesVariable[]

The declared variables.

versionnumber

1 for a new template.

createdAtstring

ISO 8601 timestamp.

updatedAtstring

ISO 8601 timestamp.

Errors

Status	Code	When
400	`missing_body`	The request has no body.
400	`invalid_body`	A field is missing or malformed, for example a name with capital letters. `param` names the field.
400	`invalid_template`	A syntax error, such as an unclosed `{{#if}}`. `param` is `subject`, `html` or `text`.
409	`template_exists`	The project already has a stored template with this name.

Request

import { Flaresend } from '@flaresend/client';

const flaresend = new Flaresend({
  apiKey: process.env.FLARESEND_API_KEY!,
  baseUrl: 'https://mailer.example.com',
});

const template = await flaresend.templates.create({
  name: 'order-shipped',
  subject: 'Order {{order.number}} is on its way',
  html: '<p>Hi {{first_name}}, your order has shipped.</p>',
  variables: [
    { name: 'first_name', required: true, example: 'Ada' },
    { name: 'order.number', required: true, example: '1042' },
  ],
});

Response

{
  "id": "tmpl_01K6B5A7C9E1G3J5L7N9Q1S3U5",
  "source": "db",
  "projectId": "proj_01K6A9W2E4R6T8Y0U2I4O6P8A0",
  "name": "order-shipped",
  "subject": "Order {{order.number}} is on its way",
  "html": "<p>Hi {{first_name}}, your order has shipped.</p>",
  "text": null,
  "variables": [
    { "name": "first_name", "required": true, "example": "Ada" },
    { "name": "order.number", "required": true, "example": "1042" }
  ],
  "version": 1,
  "createdAt": "2026-09-26T10:00:00.000Z",
  "updatedAt": "2026-09-26T10:00:00.000Z"
}

Body parametersCopy Anchor Link

ResponseCopy Anchor Link

ErrorsCopy Anchor Link

Body parameters

Response

Errors