Templates and Personalization

Templates let you standardize email layout while personalizing content per recipient and context. Use templates to keep brand structure consistent while still letting campaigns and workflows adapt the message for the recipient. A good template reduces duplicate design work and makes message changes safer to roll out.

Template Types

transactional
workflow
campaign

Choose template type based on sending channel and lifecycle context. If you are unsure, start with the message purpose: transactional templates confirm an action, workflow templates support a timed sequence, and campaign templates support a one-time broadcast.

Variable Basics

MailerPath provides built-in variables for every template send, organized by category: Company and Brand

companyName

brandName

companyAddress

companyPhone

companyWebsite

logoUrl

brandPrimaryColor

brandSecondaryColor

fromAddress

fromName

replyTo

emailSignature

unsubscribeUrl

supportEmail

supportPhone

Contact

firstName

lastName

fullName

email

phone

contactCompany

externalId

signupSource

isSubscribed

unsubscribeReason

Workflow-only

workflowId

workflowName

(available only in workflow sends) Links

viewInBrowserUrl

unsubscribeUrl

Alias behavior: Variables support snake_case, camelCase, and lowercase variants automatically. For example, companyName can also be referenced as company_name or companyname. Use canonical names in your templates for clarity.

Using Variables in Transactional Emails

When you send a transactional email, MailerPath automatically populates built-in variables from:

Contact record (first name, email, company, etc.)
Client settings (brand, sender, timezone, currency, etc.)
System defaults (unsubscribe link, view in browser link, etc.)

You reference variables in your template using Handlebars syntax:

Hello {{firstName}},

Thank you for your order, {{contactCompany}}.

Best regards,
{{fromName}}
{{supportEmail}}

{{viewInBrowserUrl}}
{{unsubscribeUrl}}

All variables are optional; missing contact fields default to empty strings, so your template renders safely even when data is incomplete.

Custom Variables

Custom variables let you send dynamic, application-specific data in addition to the built-in variables. Use them for:

Order details (order ID, total, items)
Account-specific info (plan name, renewal date, discount code)
Dynamic content (personalized recommendations, next steps, status messages)

When you send a transactional email, you provide custom variables in the API request:

{
  "template_id": 123,
  "to": {"email": "customer@example.com"},
  "vars": {
    "order_id": "ORD-12345",
    "total_amount": "$99.99",
    "shipping_address": "123 Main St, Anytown, USA",
    "estimated_delivery": "2024-06-30"
  }
}

In your template, reference custom variables the same way as built-in variables:

Order Confirmation

Order ID: {{order_id}}
Total: {{total_amount}}
Delivery: {{estimated_delivery}}

Shipping to:
{{shipping_address}}

How Variables Merge

Custom variables are merged with built-in variables. If your custom variable has the same name as a built-in variable, the custom value takes precedence. Nested objects (maps) merge recursively: Example: Built-in + Custom merge Built-in vars:

{
  "firstName": "John",
  "email": "john@example.com",
  "companyName": "Acme Inc",
  "brandPrimaryColor": "#FF0000"
}

Custom vars you send:

{
  "companyName": "John's Dept",
  "discount_code": "SAVE20",
  "brandPrimaryColor": "#0000FF"
}

Merged result in template:

{
  "firstName": "John",
  "email": "john@example.com",
  "companyName": "John's Dept",
  "discount_code": "SAVE20",
  "brandPrimaryColor": "#0000FF"
}

Custom Variable Naming Rules

Custom variables follow the same alias rules as built-in variables. Use snake_case, camelCase, or lowercase in your templates—they all work:

{{discount_code}}  // snake_case
{{discountCode}}   // camelCase
{{discountcode}}   // lowercase

All three reference the same variable.

Use Cases

1. Transactional order confirmation

{
  "vars": {
    "order_id": "ORD-12345",
    "order_date": "2024-06-20",
    "items": [
      {"name": "Widget A", "qty": 2, "price": "$29.99"},
      {"name": "Widget B", "qty": 1, "price": "$40.01"}
    ],
    "subtotal": "$99.99",
    "tax": "$7.99",
    "shipping": "$5.00",
    "total": "$112.98"
  }
}

2. Account update with personalized content

{
  "vars": {
    "plan_name": "Enterprise",
    "renewal_date": "2024-12-31",
    "annual_savings": "$500",
    "next_feature": "Workflows",
    "tutorial_url": "https://app.example.com/tutorial/workflows"
  }
}

3. Promotional email with conditional content

{
  "vars": {
    "user_segment": "VIP",
    "discount_code": "VIP20",
    "offer_expires": "2024-07-15",
    "is_first_purchase": true
  }
}

In template:

{{#if is_first_purchase}}
  Welcome! Use code {{discount_code}} for 20% off.
{{else}}
  VIP exclusive: {{discount_code}} just for you.
{{/if}}

Offer expires {{offer_expires}}.

Best Practices for Custom Variables

Use consistent naming: Stick to snake_case across all sends to avoid confusion.
Keep structure simple: 3–4 levels of nesting is ideal; avoid deeply nested structures.

Provide defaults in templates: Use Handlebars conditionals for optional custom vars.

{{#if discount_code}}
  Code: {{discount_code}}
{{else}}
  No discount available
{{/if}}

Validate before sending: Ensure email addresses are valid, URLs are formatted, numbers are in expected ranges.
Document your vars: List what custom variables your application will send so template designers know what’s available.

Data Type Support

Custom variables support:

Strings: "order_id": "ORD-12345"
Numbers: "total": 99.99
Booleans: "is_first_purchase": true
Arrays: "items": [...]
Objects: "shipping": {"address": "...", "cost": 5.00}

Recommended size limit: 16KB total for all custom variables.

Preview Text Guidance

preview_text is optional in your template.
You can clear preview text by sending null or an empty string.
Preview text renders with the same variables as the subject and body, so you can use template variables here too.

Best Practices

Keep a base template per brand or product line: Standardize layouts for consistency.
Test with incomplete data: Test rendering when optional contact fields are missing.
Keep subject lines variable-safe: Ensure subject lines stay readable if a variable is empty.
Include required links: Always include unsubscribe and view-in-browser links for compliance and user experience.
Use conditionals for optional custom vars: Wrap optional custom variables in Handlebars conditionals to handle cases where the data is missing.

Overview

Core Functionalities

Send

Events

Contact Journey

Health and AI

Analytics

Settings

Troubleshooting

Templates and Personalization

Template Types

Variable Basics

Using Variables in Transactional Emails

Custom Variables

How Variables Merge

Custom Variable Naming Rules

Use Cases

Best Practices for Custom Variables

Data Type Support

Preview Text Guidance

Best Practices

​Template Types

​Variable Basics

​Using Variables in Transactional Emails

​Custom Variables

​How Variables Merge

​Custom Variable Naming Rules

​Use Cases

​Best Practices for Custom Variables

​Data Type Support

​Preview Text Guidance

​Best Practices

Template Types

Variable Basics

Using Variables in Transactional Emails

Custom Variables

How Variables Merge

Custom Variable Naming Rules

Use Cases

Best Practices for Custom Variables

Data Type Support

Preview Text Guidance

Best Practices