Skip to main content
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

  1. Use consistent naming: Stick to snake_case across all sends to avoid confusion.
  2. Keep structure simple: 3–4 levels of nesting is ideal; avoid deeply nested structures.
  3. Provide defaults in templates: Use Handlebars conditionals for optional custom vars. 
    {{#if discount_code}}
  Code: {{discount_code}}
{{else}}
  No discount available
{{/if}}
  4. Validate before sending: Ensure email addresses are valid, URLs are formatted, numbers are in expected ranges.
  5. 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

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