Send with a template

A template is an email laid out once in the dashboard. Your code then sends it with two fields: the alias of the template and the data that fills its variables.

Prerequisites

• A verified domain and an API key.
• For the SDK examples, mailpush 0.3.0 or later.

1. Create the template

In the dashboard, open Templates, type a name and pick a Point de départ (starting point): a blank page, or one of five models (welcome, address confirmation, password reset, order confirmation, payment receipt) that come with their variables and example values. Click Créer et ouvrir l’éditeur (create and open the editor).

The alias your code will use is derived from the name: Order confirmation becomes order-confirmation. Change it under Infos (details) in the editor.

2. Build the email

The editor shows the email in the middle, drawn with the same sizes and spacing as the email MailPush sends.

Area	What you do there
Ajouter (add), on the left	Drag a block, an empty section of 1 to 4 columns or a ready section into the email. A click adds it under the selection instead.
Calques (layers), on the left	See every section and block in order, select one, and move, duplicate or remove it from the keyboard.
The email, in the middle	Click a block to select it, click a text to write in it. The bar of the selected block moves, duplicates and removes it; its handle drags it. The + under a block or a section adds something right there.
The right panel	The settings of the selection. With nothing selected: the styles of the whole email, such as the font, the brand colors and the look of buttons.

A column holds any of six blocks: text, image, button, divider, spacer and raw HTML. Images are given by their https address, MailPush does not host them yet.

The email is 600 px wide. On a phone, columns stack one under the other: switch the editor to the mobile width to check it.

Type the subject and the preview text above the email, in Objet (subject) and Texte d’aperçu (preview text). The draft is saved by itself one second after your last change.

3. Add variables

While you write in a text, click Variable in the formatting bar, or type two opening braces, and pick a name. You can also write a variable between double braces wherever you type text: in a text block, a button label, a link address, the subject.

Hello {{firstName}}, your order {{order.id}} is on its way.

Each variable you use appears in the Variables tab with an example value, lists included. Switch the editor from Noms (names) to Exemples (examples) to see the email filled in: repeated sections repeat and hidden sections fade.

4. Publish

Click Publier. MailPush compiles the draft into version 1, and that version is what every email uses from now on. Later changes stay in the draft until you publish again, so you can edit a template that is in production.

A template with no section, no subject or a tag left open cannot be published. Aperçu (preview) shows the email exactly as it leaves, on a computer and on a phone, with what to check before publishing: the size against Gmail’s 102 KB limit, images without a description, buttons without a link and missing example values.

5. Send it

Give the alias in template and the values in data.

curl https://api.mailpush.app/v1/emails \
  -H "Authorization: Bearer $MAILPUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@example.com>",
    "to": "customer@example.org",
    "template": "order-confirmation",
    "data": {
      "firstName": "Camille",
      "order": { "id": "1234" },
      "items": [{ "name": "Notebook", "price": "12.50" }]
    }
  }'

await mailpush.emails.send({
  from: "Acme <hello@example.com>",
  to: "customer@example.org",
  template: "order-confirmation",
  data: {
    firstName: "Camille",
    order: { id: "1234" },
    items: [{ name: "Notebook", price: "12.50" }],
  },
});

The subject and the content come from the published version. To change the subject for one email, add subject to the request. html and text are refused next to template.

Variables, conditions and loops

You write	What is sent
{{firstName}}	The value of firstName.
{{order.id}}	The value of id inside the object order.
{{#if premium}}Free delivery{{else}}Delivery: 4.90{{/if}}	The first text when premium is true, the second otherwise. {{else}} is optional.
{{#each items}}{{name}}, {{/each}}	The text between the tags, once per item of the list. Inside, names are read on the item first.

Every value is escaped: a < in your data is shown as a <, it never becomes HTML.

A condition is false when the variable is missing, false, 0, an empty text or an empty list.

Repeat or hide a whole section

A row of an order usually spans several columns. Select the section and use Données (data) in its settings.

Setting	Effect
Répéter pour chaque élément d’une liste (repeat for each item of a list)	The name of a list, such as items. The section is sent once per item, and its variables are read on the item.
Afficher cette section : Seulement si… (show this section: only if)	The name of a variable. The section is sent only when that variable is true or not empty.

Missing data

Every variable the email prints must be in data. If one is missing, nothing is sent and the API answers 422:

{
  "error": {
    "code": "missing_template_data",
    "message": "data lacks what the template needs: order.id, items[].price"
  }
}

A variable that is only tested by an {{#if}} may be left out. So may a variable inside a branch or a section that is not sent.

Versions

Each publication adds a version to Versions publiées (published versions), under Infos in the editor. Click Reprendre dans le brouillon (bring back into the draft) on an older one to copy it into the draft, then publish to put it back in production.

An email already accepted by the API keeps the content it had when it was accepted.

Send a test from the dashboard

Envoyer un test sends the draft, filled with the example data, to the address you choose. It is a real email: it leaves from one of your verified domains and counts against your daily quota.

Next steps

• Send an email: template, data and the other parameters.
• Errors: template_not_found, template_not_published and missing_template_data.
• Limits: templates per account, sections and blocks per template.