← Back to docs

Template Engine

Create and manage email templates with MiniJinja

Menu

MiniJinja Templating

EuroMail uses MiniJinja as its template engine, which provides Jinja2-compatible syntax familiar to developers who have worked with Python, Ansible, or static site generators. Templates are rendered server-side before SMTP delivery, so recipients receive fully composed HTML emails.

Variable Substitution

Put a variable name in double curly braces to insert its value:

<h1>Hello, {{ customer_name }}!</h1>
<p>Your order <strong>#{{ order_id }}</strong> has been confirmed.</p>

When sending an email, name the template by its alias in template_alias and pass the values in template_data:

{
  "from": "[email protected]",
  "to": "[email protected]",
  "template_alias": "order-confirmation",
  "template_data": {
    "customer_name": "Anna",
    "order_id": "EM-20260309-4821"
  }
}

Missing variables

If the template prints a variable that template_data doesn't include, the API refuses the send with 422 and names the missing variables:

{
  "error": {
    "type": "validation_error",
    "code": "VALIDATION_ERROR",
    "message": "Template 'order-confirmation' cannot be sent: template_data is missing variable(s) the template uses: order_id"
  }
}

So a password-reset email never goes out with a blank where the link should be. If a value is genuinely optional, wrap it in {% if %} or give it a fallback with default. Neither counts as missing:

{% if coupon_code %}<p>Your code: {{ coupon_code }}</p>{% endif %}
<p>Hello {{ first_name | default("there") }},</p>

Contact variables in newsletters and broadcasts

In a newsletter or broadcast to a contact list, each recipient's template data also has a contact object with their address and the metadata stored on their contact: {{ contact.email }}, {{ contact.first_name }} and so on. You don't pass it yourself. It's added to your template_data once per recipient, and contact is a reserved name. Since a missing value fails the send (see above), give fields that not every contact has a fallback: {{ contact.first_name | default("there") }}. See Contact variables in templates.

Conditionals, Loops, and Filters

MiniJinja supports control flow and data transformation within templates:

{% if shipping_method == "express" %}
  <p>Your order will arrive within 1-2 business days.</p>
{% else %}
  <p>Your order will arrive within 5-7 business days.</p>
{% endif %}

<h2>Order Items</h2>
<table>
  {% for item in items %}
  <tr>
    <td>{{ item.name }}</td>
    <td>{{ item.quantity }}</td>
    <td>{{ item.price | round(2) }} EUR</td>
  </tr>
  {% endfor %}
</table>

<p>Total: {{ total | round(2) }} EUR</p>

Filters like round, upper, lower, length, and default are available for transforming values inline.

Managing Templates via API

Templates can be created, updated, and versioned through the REST API:

curl -X POST https://api.euromail.dev/v1/templates \
  -H "Authorization: Bearer em_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "order-confirmation",
    "name": "Order confirmation",
    "subject": "Order #{{ order_id }} Confirmed",
    "html_body": "<h1>Thanks, {{ customer_name }}!</h1>..."
  }'

Sends refer to the template by its alias in template_alias. An alias is up to 100 characters of lowercase letters, digits, hyphens and underscores, and starts with a letter or digit (for example order-confirmation or welcome_v2). name is the display name in the dashboard. A template needs an html_body, a text_body, or both; saving one with neither fails.

To read, change or remove templates:

# All templates (paged with page and per_page)
curl "https://api.euromail.dev/v1/templates?page=1&per_page=25" \
  -H "Authorization: Bearer em_live_..."

# One template
curl https://api.euromail.dev/v1/templates/{id} \
  -H "Authorization: Bearer em_live_..."

# Replace its content
curl -X PUT https://api.euromail.dev/v1/templates/{id} \
  -H "Authorization: Bearer em_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order confirmation",
    "subject": "Order #{{ order_id }} confirmed",
    "html_body": "<h1>Thanks, {{ customer_name }}!</h1>...",
    "text_body": "Thanks, {{ customer_name }}!"
  }'

# Delete it
curl -X DELETE https://api.euromail.dev/v1/templates/{id} \
  -H "Authorization: Bearer em_live_..."

An update replaces the template: name and subject are required, and a body or preheader you leave out is cleared. The alias cannot be changed. A delete returns 204 No Content. All template calls need the templates:manage scope.

Preheader

The optional preheader is the preview line most inboxes show after the subject. It can use variables like the subject and bodies do. At send time it is rendered with template_data, escaped, and placed as a hidden block right after the HTML part's opening <body> tag (or at the very start when there is none). Leave it out or empty and the HTML is sent unchanged; mail clients then show the first text of the message instead. A template with only a text body has no HTML part, so its preheader is not used.

{ "preheader": "Your order {{ order_id }} ships today" }

You can also manage templates through the dashboard, which provides a visual editor with live preview.

Template Versioning

Every update to a template creates a new version. Previous versions are retained, allowing you to roll back if needed. The API returns the current version number with each template response.

Server-Side Rendering

The API renders the template when you send, so a missing variable or an empty body gets a 422 right away. The worker renders it again just before SMTP delivery, and the recipient's mail client receives a fully rendered email with no template syntax left in it. Edits to a template apply to sends made after the edit, not to sends already accepted: a scheduled or queued send is delivered with the template version it was accepted with. If that version has since been deleted, the email fails rather than going out with a different one.

The dashboard preview is more lenient. Variables missing from the sample data render blank, and a warning above the preview lists them so you can fix them before a real send.

Send your first email in about 90 seconds

The free tier includes 3,000 emails a month. Email storage and AI processing in Finland, with a DPA on every plan.

Create free account See live delivery data