Templates

A template defines the subject and body (HTML and/or plain text) of emails. Campaigns and sequences reference it by id — you can update the template without touching the campaign, and change the content before sending. This lets you iterate on copy or design without having to edit each campaign separately.

Schema

Field	Type	Description
id	string	Slug identifier for the template.
name	string	Descriptive name to identify it in the dashboard.
subject	string	Email subject. Supports merge tags.
html	string	HTML body. Supports merge tags.
body_text	string	Plain-text body. Supports merge tags.
key_id	string	API key this template belongs to.
created_at	string	Creation date (ISO 8601).
updated_at	string	Last updated date (ISO 8601).

Merge tags

You can personalize the subject and body using {{name}} to insert the contact’s name. MailerDash replaces the tag at send time with the value of the name field on the recipient contact.

Example:

subject: "Hi {{name}}, your report is ready"
html:    "<h1>Hi {{name}},</h1><p>Your monthly report is available.</p>"

If the contact has no name, the tag is replaced with an empty string.

You can also use any field from the contact’s metadata: if you imported a company column, {{company}} works.

Platform tags

MailerDash generates these at send time, one per recipient. You can’t define them yourself: if your metadata carries a field with one of these names, it’s ignored and ours wins. The reason is that they carry a signed token only we can issue — an unsubscribe link pointing somewhere else is an email that looks compliant and isn’t.

Tag	What it inserts
{{unsubscribe_url}}	Unsubscribe link. Required: a template without it is rejected with 400 on save.
{{preferences_url}}	Preference center, to adjust what they receive instead of leaving entirely.
{{physical_address}}	Your postal address. A CAN-SPAM requirement.
{{reconfirm_url}}	Re-confirmation link for re-engagement campaigns. See campaigns.

The editor warns you while you work if the template carries no {{unsubscribe_url}} anywhere —not in the HTML, not in the MJML, not in the plain text— so you don’t hit the 400 once you thought you were done. The warning comes with an “Add to footer” button that inserts it for you: it writes on whichever field has content, and if your template is plain text only it adds a readable line instead of inventing an HTML body for you.

The visual editor also ships a drag-and-drop “Legal footer” block with the unsubscribe link and your postal address — the two things CAN-SPAM §7704 asks for. The address lives only in that block, where you can see it and remove it, and not in what the button inserts: if your account hasn’t set one, it would leave an empty line in the email.

Tip

Offering the preference center next to the unsubscribe link reduces total unsubscribes: someone who just wanted fewer emails doesn’t have to leave completely to get that — which is exactly the path that ends at the spam button.

Operations

List templates

GET /v1/bulk/templates

Returns an array with all templates in your account.

---

Create a template

POST /v1/bulk/templates

Body:

{
  "name": "Bienvenida onboarding",
  "subject": "Bienvenido a bordo, {{name}}",
  "html": "<h1>Hola {{name}},</h1><p>Tu cuenta está lista.</p>",
  "body_text": "Hola {{name}},\n\nTu cuenta está lista."
}

name and subject are required. Returns 201 with the created template.

---

Get a template

GET /v1/bulk/templates/{id}

Returns all fields of the template, including html and body_text.

---

Update a template

PATCH /v1/bulk/templates/{id}

Body (all fields are optional):

{
  "subject": "¡Bienvenido, {{name}}!",
  "html": "<h1>Hola {{name}},</h1><p>Tu cuenta está lista. Empieza ahora.</p>"
}

Returns 200 with the updated template. Fields you don’t send are not modified.

---

Delete a template

DELETE /v1/bulk/templates/{id}

Deletes the template. Returns 204 No Content. If it is referenced by an active campaign, returns 409 Conflict.

---

Bulk delete templates

POST /v1/bulk/templates/delete

Atomic deletion of multiple templates. Body:

{ "ids": ["bienvenida-onboarding-abc", "promo-verano-xyz"] }

Response:

{
  "requested": 2,
  "deleted": 1,
  "not_found": [],
  "forbidden": [],
  "in_use": ["promo-verano-xyz"]
}

Templates in use by active campaigns are reported in in_use and are not deleted. The rest are deleted in the same request.

Example

Create a template with HTML and plain text

curl -X POST https://api.mailerdash.com/v1/bulk/templates \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bienvenida onboarding",
    "subject": "Bienvenido a bordo, {{name}}",
    "html": "<h1>Hola {{name}},</h1><p>Tu cuenta está lista.</p>",
    "body_text": "Hola {{name}},\n\nTu cuenta está lista."
  }'

Tip

Always include body_text alongside html. Email clients that don’t render HTML — some corporate clients and many mobile clients in data-saving mode — display the plain text as a fallback. Having both versions also improves sender reputation and helps deliverability.

Caution

You cannot delete a template referenced by an active campaign. The bulk delete reports in_use templates without deleting them — the rest are deleted. To free up a template, cancel or complete the campaigns using it first.

Reference

For the full request/response schema and error codes, see the bulk API reference.