Skip to content
MailMarcodocs

05 · MailMarco API

Templates

Templates are append-only. You add versions and publish exactly one of them; sends always render the published version.

The version model

  • A template is a name plus a pointer, currentVersion, to the published version.
  • A version is an immutable subject plus at least one of html, text or reactSource. Version numbers start at 1 and are assigned server-side.
  • Editing means adding a new version and publishing it. Nothing is ever mutated in place, so a message sent yesterday can still be explained by the version that was live then.
  • Writes take an API key; reads (GET /v1/templates and GET /v1/templates/:id) take a session token.

Create a template

POST/v1/templates
auth: API key201 on success

Creates an empty template with no versions.

Body

name
stringrequired
1–120 characters.
request
curl -X POST https://api.mailmarco.com/v1/templates \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"order-receipt"}'
response · 201
{
  "id": "7d3c9b21-4a5e-4f6a-8b7c-0d1e2f3a4b5c",
  "name": "order-receipt",
  "currentVersion": null
}

Add a version

POST/v1/templates/{id}/versions
auth: API key201 on success

Appends a version. The version number is the current maximum plus one.

Path parameters

id
string (uuid)required
Template id.

Body

subject
stringrequired
At least 1 character. Used as the message subject when sending.
html
stringoptional
HTML body.
text
stringoptional
Plain-text body.
reactSource
stringoptional
React Email source, rendered server-side.
request
curl -X POST https://api.mailmarco.com/v1/templates/$TEMPLATE_ID/versions \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "subject": "Receipt for {{ orderId }}",
    "html": "<p>Hi {{ name }}, your total was {{ total }}.</p>",
    "text": "Hi {{ name }}, your total was {{ total }}."
  }'

Errors

  • 400 — None of html, text or reactSource was supplied.
  • 404 — No template with that id.

Publish a version

POST/v1/templates/{id}/publish
auth: API key201 on success

Marks a version published and points the template at it. Sends immediately start using it.

Path parameters

id
string (uuid)required
Template id.

Body

version
integerrequired
A positive version number that exists on this template.
request
curl -X POST https://api.mailmarco.com/v1/templates/$TEMPLATE_ID/publish \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"version":1}'
response · 201
{
  "id": "7d3c9b21-4a5e-4f6a-8b7c-0d1e2f3a4b5c",
  "name": "order-receipt",
  "currentVersion": 1
}

Errors

  • 404 — No such template, or that version number does not exist.

Sending with a template

Replace subject/html/text with a template object on the send endpoint.

body fragment
{
  "from": "[email protected]",
  "to": "[email protected]",
  "template": {
    "id": "7d3c9b21-4a5e-4f6a-8b7c-0d1e2f3a4b5c",
    "variables": { "name": "Ada", "orderId": "2291", "total": "€42.00" }
  }
}

Interpolation is deliberately not a template engine. {{ name }} resolves a bare dotted identifier such as {{ user.firstName }} and nothing else — an expression or function call renders as an empty string rather than executing. Every substituted value is HTML-escaped, and dangerous URL schemes (javascript:, vbscript:, non-image data:) are stripped so a variable dropped into an href cannot smuggle script execution. A missing variable renders as an empty string.