Email Templates

Create and manage email templates in Mailtura

Mailtura supports powerful templating capabilities to create dynamic, personalized emails for your applications.

Template Syntax

Mailtura uses Handlebars-style template syntax for dynamic content:

<h1>Hello {{firstName}}!</h1>
<p>Welcome to {{companyName}}. Your account has been created.</p>

Creating Templates

Via API

Create a new template:

curl -X POST https://your-mailtura-instance.com/api/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome-email",
    "subject": "Welcome to {{companyName}}",
    "html": "<h1>Hello {{firstName}}!</h1><p>Welcome aboard!</p>",
    "text": "Hello {{firstName}}! Welcome aboard!"
  }'

Template Structure

A complete template includes:

  • name: Unique identifier for the template
  • subject: Email subject line (supports variables)
  • html: HTML version of the email
  • text: Plain text version (fallback)
  • variables: Optional schema defining expected variables

Template Variables

Basic Variables

Simple variable substitution:

Hello {{userName}}!
Your order #{{orderId}} has been confirmed.

Conditional Blocks

Show content conditionally:

{{#if isPremium}}
  <p>Enjoy your premium features!</p>
{{else}}
  <p>Upgrade to premium for more features.</p>
{{/if}}

Loops

Iterate over arrays:

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

Template Best Practices

Responsive Design

Always design mobile-responsive templates:

<table width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td style="max-width: 600px; margin: 0 auto;">
      <!-- Your content here -->
    </td>
  </tr>
</table>

Inline CSS

Email clients require inline styles:

<p style="color: #333; font-size: 16px; line-height: 1.5;">
  Your content here
</p>

Fallback Text

Always provide a plain text version:

Hello {{userName}}!

Your order #{{orderId}} has been confirmed.

Thank you for your purchase!

Testing Templates

Preview Templates

Preview a template with sample data:

curl -X POST https://your-mailtura-instance.com/api/v1/templates/welcome-email/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "companyName": "Acme Corp"
  }'

Send Test Email

Send a test to verify rendering:

curl -X POST https://your-mailtura-instance.com/api/v1/templates/welcome-email/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "test@example.com",
    "variables": {
      "firstName": "John",
      "companyName": "Acme Corp"
    }
  }'

Template Management

List Templates

curl https://your-mailtura-instance.com/api/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: acme-corp"

Update Template

curl -X PATCH https://your-mailtura-instance.com/api/v1/templates/welcome-email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Welcome to {{companyName}} - Updated"
  }'

Delete Template

curl -X DELETE https://your-mailtura-instance.com/api/v1/templates/welcome-email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: acme-corp"

Next Steps