Documentation / Guides

Templates

3 min read

Templates let you create reusable email designs that you can send with dynamic content. Define your layout once, then personalize for each recipient.

Why use templates

Without templates:

  • Duplicate HTML across API calls
  • Hard to maintain consistent branding
  • Changes require updating all integrations
  • Easy to introduce errors

With templates:

  • Define layout once, reuse everywhere
  • Update branding in one place
  • Non-technical team members can edit
  • Preview and test before sending

Creating a template

Via Dashboard

  1. Go to Templates
  2. Click Create template
  3. Design your email using the visual editor
  4. Add variables for dynamic content
  5. Preview and test
  6. Click Save

Via API

curl -X POST https://api.mailingapi.com/v1/templates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_email",
    "subject": "Welcome to {{company_name}}, {{name}}!",
    "html": "<h1>Welcome, {{name}}!</h1><p>Your account is ready.</p>",
    "text": "Welcome, {{name}}!\n\nYour account is ready."
  }'

Response:

{
  "id": "tmpl_abc123",
  "name": "welcome_email",
  "subject": "Welcome to {{company_name}}, {{name}}!",
  "status": "active",
  "created_at": "2024-01-15T10:00:00Z"
}

Template variables

Use double braces for dynamic content:

<h1>Hello, {{name}}!</h1>
<p>Your order #{{order_id}} has shipped.</p>
<p>Track it here: <a href="{{tracking_url}}">{{tracking_url}}</a></p>

Variable types

Simple values:

{{name}}
{{email}}
{{order_id}}

Nested objects:

{{user.first_name}}
{{order.total}}
{{company.address.city}}

Default values:

{{name|default:"Customer"}}
{{company|default:"Our Team"}}

Reserved variables

These are automatically available:

Variable Description
{{unsubscribe_url}} One-click unsubscribe link
{{preferences_url}} Email preferences page
{{view_in_browser}} Web version of the email
{{current_year}} Current year (e.g., 2024)

Conditionals

Show content based on conditions:

{{#if premium_user}}
  <p>Thanks for being a premium member!</p>
{{else}}
  <p>Upgrade to premium for exclusive benefits.</p>
{{/if}}

Check for values:

{{#if tracking_number}}
  <p>Track your package: {{tracking_number}}</p>
{{/if}}

Compare values:

{{#if order_total > 100}}
  <p>You qualify for free shipping!</p>
{{/if}}

Loops

Iterate over arrays:

<h2>Your order:</h2>
<ul>
{{#each items}}
  <li>{{this.name}} - ${{this.price}}</li>
{{/each}}
</ul>

With index:

{{#each items}}
  <tr class="{{#if @odd}}odd{{/if}}">
    <td>{{@index}}. {{this.name}}</td>
  </tr>
{{/each}}

Partials

Reuse common sections across templates:

Create a partial

curl -X POST https://api.mailingapi.com/v1/templates/partials \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "name": "footer",
    "html": "<footer><p>© {{current_year}} {{company_name}}</p></footer>"
  }'

Use in templates

<body>
  <h1>Welcome!</h1>
  <p>Content here...</p>

  {{> footer}}
</body>

Common partials:

  • Headers with logo
  • Footers with legal text
  • Social media links
  • Address blocks

Sending with templates

Basic send

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "user@example.com",
    "template_id": "tmpl_abc123",
    "variables": {
      "name": "John",
      "order_id": "12345",
      "company_name": "Acme Inc"
    }
  }'

Batch send with templates

curl -X POST https://api.mailingapi.com/v1/messages/batch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "template_id": "tmpl_abc123",
    "recipient_variables": {
      "alice@example.com": {"name": "Alice", "order_id": "001"},
      "bob@example.com": {"name": "Bob", "order_id": "002"}
    }
  }'

Template versions

Keep track of changes with versioning:

Create a new version

curl -X POST https://api.mailingapi.com/v1/templates/tmpl_abc123/versions \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "html": "<h1>Updated welcome email</h1>...",
    "changelog": "Refreshed design for 2024"
  }'

List versions

curl https://api.mailingapi.com/v1/templates/tmpl_abc123/versions \
  -H "Authorization: Bearer $API_KEY"

Restore version

curl -X POST https://api.mailingapi.com/v1/templates/tmpl_abc123/versions/2/restore \
  -H "Authorization: Bearer $API_KEY"

Preview and testing

Preview with data

curl -X POST https://api.mailingapi.com/v1/templates/tmpl_abc123/render \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "variables": {
      "name": "Test User",
      "order_id": "TEST-001"
    }
  }'

Returns rendered HTML and text.

Send test email

curl -X POST https://api.mailingapi.com/v1/templates/tmpl_abc123/test \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "to": "your-email@example.com",
    "variables": {
      "name": "Test User"
    }
  }'

Template categories

Organize templates by type:

curl -X POST https://api.mailingapi.com/v1/templates \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "name": "order_shipped",
    "category": "transactional",
    "tags": ["orders", "shipping"]
  }'

Common categories:

  • transactional — Receipts, confirmations, alerts
  • marketing — Newsletters, promotions
  • notification — Updates, reminders
  • authentication — Password reset, verification

Managing templates

List all templates

curl https://api.mailingapi.com/v1/templates \
  -H "Authorization: Bearer $API_KEY"

Get single template

curl https://api.mailingapi.com/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer $API_KEY"

Update template

curl -X PATCH https://api.mailingapi.com/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"subject": "New subject line"}'

Delete template

curl -X DELETE https://api.mailingapi.com/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer $API_KEY"

Best practices

  1. Use descriptive names — order_confirmation not template1
  2. Always include text version — Some clients don’t render HTML
  3. Test with real data — Preview before sending to customers
  4. Keep it simple — Complex logic belongs in your app
  5. Version your templates — Track changes, enable rollback
  6. Use partials — DRY principle for headers/footers
  7. Mobile-first — Most emails are read on mobile

Email design tips

Responsive layout

<table width="100%" style="max-width: 600px; margin: 0 auto;">
  <tr>
    <td style="padding: 20px;">
<!-- Content -->

    </td>
  </tr>
</table>

Safe fonts

font-family: Arial, Helvetica, sans-serif;
font-family: Georgia, Times, serif;

Inline styles

Email clients strip <style> tags. Always inline:

<!-- Good -->

<p style="color: #333; font-size: 16px;">Text</p>

<!-- Bad (may not work) -->

<p class="body-text">Text</p>

Next steps