Templates

How templates work

Email templates let you send flexible, custom emails to many different recipients in a single request. MailChannels currently supports Mustache templates.

Enabling templates

Two changes turn a regular send into a template send. 1. Mark the content part as a template.

"content": [
  {
    "type": "text/plain",
    "value": "Hello {{name}}",
    "template_type": "mustache"
  }
]

template: { type: "mustache" },
text: "Hello {{name}}",

"content": [
    {
        "type": "text/plain",
        "value": "Hello {{name}}",
        "template_type": "mustache",
    },
],

'content' => [
    [
        'type'          => 'text/plain',
        'value'         => 'Hello {{name}}',
        'template_type' => 'mustache',
    ],
],

The template type field must be set in each content part that contains a template. Otherwise, that content part will not be modified, and any templating within will be sent as normal text. The JavaScript SDK avoids this by applying template.type to all content parts.

2. Supply per-recipient data. Add per-recipient template data to each personalization. The keys must match the placeholders in your template:

"personalizations": [
  { "to": [{ "email": "alice@example.com" }], "dynamic_template_data": { "name": "Alice" } },
  { "to": [{ "email": "bob@example.com" }],   "dynamic_template_data": { "name": "Bob"   } }
]

personalizations: [
  { to: [{ email: "alice@example.com" }], template: { data: { name: "Alice" } } },
  { to: [{ email: "bob@example.com" }],   template: { data: { name: "Bob"   } } },
],

"personalizations": [
    {"to": [{"email": "alice@example.com"}], "dynamic_template_data": {"name": "Alice"}},
    {"to": [{"email": "bob@example.com"}],   "dynamic_template_data": {"name": "Bob"}},
],

'personalizations' => [
    ['to' => [['email' => 'alice@example.com']], 'dynamic_template_data' => ['name' => 'Alice']],
    ['to' => [['email' => 'bob@example.com']],   'dynamic_template_data' => ['name' => 'Bob']],
],

Placeholders without a matching key in dynamic_template_data render as empty strings.

Full example

#!/usr/bin/env bash
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"
: "${FROM_EMAIL:?Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)}"
: "${TO_EMAIL_1:?Set TO_EMAIL_1}"
: "${TO_EMAIL_2:?Set TO_EMAIL_2}"

curl -X POST https://api.mailchannels.net/tx/v1/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
  -d @- <<JSON
{
  "personalizations": [
    { "to": [{ "email": "$TO_EMAIL_1" }], "dynamic_template_data": { "name": "Alice" } },
    { "to": [{ "email": "$TO_EMAIL_2" }], "dynamic_template_data": { "name": "Bob"   } }
  ],
  "from":    { "email": "$FROM_EMAIL" },
  "subject": "Hello from MailChannels",
  "content": [
    {
      "type": "text/plain",
      "value": "Hello {{name}}",
      "template_type": "mustache"
    }
  ]
}
JSON

import { MailChannels } from "mailchannels-sdk";

const { MAILCHANNELS_API_KEY, FROM_EMAIL, TO_EMAIL_1, TO_EMAIL_2 } = process.env;
if (!MAILCHANNELS_API_KEY) throw new Error("Set MAILCHANNELS_API_KEY before running");
if (!FROM_EMAIL) throw new Error("Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)");
if (!TO_EMAIL_1) throw new Error("Set TO_EMAIL_1");
if (!TO_EMAIL_2) throw new Error("Set TO_EMAIL_2");

const mailchannels = new MailChannels(MAILCHANNELS_API_KEY);

const { data, error } = await mailchannels.emails.send({
  from: FROM_EMAIL,
  subject: "Hello from MailChannels",
  text: "Hello {{name}}",
  template: { type: "mustache" },
  personalizations: [
    { to: [{ email: TO_EMAIL_1 }], template: { data: { name: "Alice" } } },
    { to: [{ email: TO_EMAIL_2 }], template: { data: { name: "Bob"   } } },
  ],
});

if (error) {
  console.error("Send failed:", error);
  process.exit(1);
}
console.log(data);

import os
import sys

import mailchannels

if not os.environ.get("MAILCHANNELS_API_KEY"):
    sys.exit("Set MAILCHANNELS_API_KEY before running")

from_email = os.environ.get("FROM_EMAIL")
to_email_1 = os.environ.get("TO_EMAIL_1")
to_email_2 = os.environ.get("TO_EMAIL_2")
if not from_email:
    sys.exit("Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)")
if not to_email_1:
    sys.exit("Set TO_EMAIL_1")
if not to_email_2:
    sys.exit("Set TO_EMAIL_2")

response = mailchannels.Emails.send(
    {
        "from": {"email": from_email},
        "subject": "Hello from MailChannels",
        "content": [
            {
                "type": "text/plain",
                "value": "Hello {{name}}",
                "template_type": "mustache",
            },
        ],
        "personalizations": [
            {"to": [{"email": to_email_1}], "dynamic_template_data": {"name": "Alice"}},
            {"to": [{"email": to_email_2}], "dynamic_template_data": {"name": "Bob"}},
        ],
    }
)

print(response)

<?php

require_once __DIR__ . '/vendor/autoload.php';

use MailChannels\Client;

$api_key    = getenv('MAILCHANNELS_API_KEY') or exit("Error: MAILCHANNELS_API_KEY is not set\n");
$from_email = getenv('FROM_EMAIL') or exit("Error: FROM_EMAIL is not set\n");
$to_email_1 = getenv('TO_EMAIL_1') or exit("Error: TO_EMAIL_1 is not set\n");
$to_email_2 = getenv('TO_EMAIL_2') or exit("Error: TO_EMAIL_2 is not set\n");

$client = new Client(apiKey: $api_key);

$response = $client->emails->send([
    'from'    => ['email' => $from_email],
    'subject' => 'Hello from MailChannels',
    'content' => [
        [
            'type'          => 'text/plain',
            'value'         => 'Hello {{name}}',
            'template_type' => 'mustache',
        ],
    ],
    'personalizations' => [
        ['to' => [['email' => $to_email_1]], 'dynamic_template_data' => ['name' => 'Alice']],
        ['to' => [['email' => $to_email_2]], 'dynamic_template_data' => ['name' => 'Bob']],
    ],
]);

print_r($response->toArray());

Alice receives Hello Alice and Bob receives Hello Bob.

Testing checklist

Render the template with typical, empty, and unusually long values.
Verify links and unsubscribe behavior.
Preview in common email clients.
Check message size before adding attachments.
Confirm Gmail does not clip long messages.
Send a test through a real domain with SPF, DKIM, and DMARC configured.

Mustache features

Mustache is a simple and flexible templating language that allows you to create custom messages for all your recipients. See the Mustache spec for the complete reference; features not in the supported features list at the bottom of this page are not available.

Nested fields

Use . to access nested fields. Data

"dynamic_template_data": {
  "name": { "title": "Ms.", "first": "Jane", "last": "Doe" }
}

Template

Dear {{name.title}} {{name.last}}, your account name is {{name.first}} {{name.last}}.

Result

Dear Ms. Doe, your account name is Jane Doe.

Lists

Wrap a section in {{#list}}…{{/list}} to repeat it for each item. Inside the section, unqualified keys refer to fields of the current item. Data

"dynamic_template_data": {
  "items": [
    { "name": "Standard plan", "price": "9.99" },
    { "name": "Add-on seat",   "price": "4.00" }
  ]
}

Template

<ul>
{{#items}}<li>{{name}}: ${{price}}</li>
{{/items}}</ul>

Result

<ul>
<li>Standard plan: $9.99</li>
<li>Add-on seat: $4.00</li>
</ul>

Conditionals

The same {{#key}}…{{/key}} syntax renders the block only when key is truthy: boolean true, a non-empty list, or any non-false value. Other fields in the data can be referenced inside the block. Template

Thanks for being a customer!{{#anniversary}} You've been with us for {{years}} year(s) — here's a code: 50OFF{{/anniversary}}

With "anniversary": true, "years": 3:

Thanks for being a customer! You've been with us for 3 year(s) — here's a code: 50OFF

With "anniversary": false:

Thanks for being a customer!

Negated conditionals

The inverse — {{^key}}…{{/key}} — renders only when key is falsy or missing. Template

{{#verified}}Your account is verified.{{/verified}}{{^verified}}Verification failed.{{/verified}}

With "verified": true:

Your account is verified.

With "verified": false:

Verification failed.

HTML escaping

{{value}} HTML-escapes its output so injected content can’t break the layout. To insert content as raw HTML, use either triple braces or {{&value}}. Data

"dynamic_template_data": { "msg": "<b>Bold</b>" }

Template

escaped: {{msg}}
raw (triple):  {{{msg}}}
raw (ampersand): {{&msg}}

Result

escaped: &lt;b&gt;Bold&lt;/b&gt;
raw (triple):  <b>Bold</b>
raw (ampersand): <b>Bold</b>

Only emit raw HTML for content you control. Substituting recipient-supplied values without escaping is a common HTML injection vector.

Comments

{{! ... }} is stripped from the rendered output. Template

Welcome.{{! TODO: add personalization here }} Glad to have you.

Result

Welcome. Glad to have you.

Supported features

The Mustache features MailChannels supports, using the names from the Mustache spec:

Variables
Dotted names
Implicit iterator
Non-empty lists
Non-false values
Inverted sections
Comments
Set delimiter

Get Started

API Reference

Authentication & Account Setup

Sending Email

Email Authentication

Webhooks & Delivery Events

Platform & Multi-tenant

Reputation and Abuse Control

Metrics & Monitoring

Operate in production

Migration guides

Integrations

For AI Agents

How templates work

Enabling templates

Full example

Testing checklist

Mustache features

Nested fields

Lists

Conditionals

Negated conditionals

HTML escaping

Comments

Supported features

​How templates work

​Enabling templates

​Full example

​Testing checklist

​Mustache features

​Nested fields

​Lists

​Conditionals

​Negated conditionals

​HTML escaping

​Comments

​Supported features

How templates work

Enabling templates

Full example

Testing checklist

Mustache features

Nested fields

Lists

Conditionals

Negated conditionals

HTML escaping

Comments

Supported features