API Reference

Create template

POST /templates — save a reusable template.

POST/templates

Creates a template with status: "draft". Provide a name and at least one of html or text. Returns { object: "template", id }. A draft cannot be sent yet — call `POST /templates/:id/publish` before referencing it as a template_id, or the send fails with validation_error.

Body parameters

namestringrequired

A name for the template (shown in the dashboard).

aliasstringoptional

A unique, human-readable handle. Pass alias instead of id wherever a template id is accepted (e.g. template_id on sends, GET /templates/:id). Must be unique across your templates.

subjectstringoptional

Default subject line. Supports {{ variables }}. Can be overridden when sending.

htmlstringoptional

HTML body. Required if text is omitted. Supports {{ variables }}.

textstringoptional

Plain-text body. Required if html is omitted. Supports {{ variables }}. If omitted, a plain-text version is generated from the HTML; set it to an empty string to opt out.

fromstringoptional

Default sender address. Use "Your Name <sender@domain.com>" for a friendly name. Can be overridden when sending.

reply_tostring | string[]optional

Default Reply-To address, or an array of addresses. An array is stored — and returned by GET /templates/:id — as a single comma-separated string. Can be overridden when sending.

variablesarrayoptional

The variables used in the template (up to 50). Each is an object with key, type, and an optional fallback_value — see below.

variables[] object

keystringrequired

The variable key. We recommend capitalizing it (e.g. PRODUCT_NAME). Reserved names that cannot be used: FIRST_NAME, LAST_NAME, EMAIL, UNSUBSCRIBE_URL, contact, this. Keys must start with a letter or underscore and contain only letters, digits, underscores, or dots.

type'string' | 'number'optional

The type of the variable. Defaults to string when omitted.

fallback_valuestring | number | nulloptional

The value used when none is supplied at send time. Must match type. If omitted, a value for this variable is required when sending.

import { Mailblastr } from 'mailblastr';

const mb = new Mailblastr('mb_xxxxxxxxx');

const { data, error } = await mb.templates.create({
  "name": "Welcome email",
  "subject": "Welcome, {{first_name}}!",
  "html": "<h1>Hi {{first_name}}</h1>"
});
console.log({ data, error });

Field limits

These caps are enforced at the API boundary. Exceeding one returns a validation_error naming the field, e.g. *subject must be 998 characters or fewer.*

Field	Maximum length
`name`	255
`subject`	998
`from`	320
`reply_to`	320
`alias`	255

Response

Returns { object: "template", id } — a slim acknowledgement. Fetch the full object with GET /templates/:id.

{
  "object": "template",
  "id": "43f68331-0622-4e15-8202-246a0388854b"
}

Errors: missing_required_field if name is absent; validation_error if neither html nor text is provided, if any field above exceeds its maximum length, if the alias is already used by another of your templates, if variables is not an array or holds more than 50 entries, or if a variable uses a reserved key, a duplicate key, an invalid key, an unknown type, or a fallback_value that does not match its type. See Errors.