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 }. Use POST /templates/:id/publish to publish the draft.

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. 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 });

Response

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

{
  "object": "template",
  "id": "tmpl_8f5c2a1e"
}

Errors: missing_required_field if name is absent; validation_error if neither html nor text is provided, or if a variable uses a reserved key or a fallback_value that does not match its type.