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.

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.