> ## Documentation Index > Fetch the complete documentation index at: https://docs.mailerpath.com/llms.txt > Use this file to discover all available pages before exploring further. # Templates and Personalization > Build reusable layouts and personalize messages with variables. 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: ```handlebars theme={null} 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: ```json theme={null} { "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: ```handlebars theme={null} 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: ```json theme={null} { "firstName": "John", "email": "john@example.com", "companyName": "Acme Inc", "brandPrimaryColor": "#FF0000" } ``` Custom vars you send: ```json theme={null} { "companyName": "John's Dept", "discount_code": "SAVE20", "brandPrimaryColor": "#0000FF" } ``` Merged result in template: ```json theme={null} { "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: ```handlebars theme={null} {{discount_code}} // snake_case {{discountCode}} // camelCase {{discountcode}} // lowercase ``` All three reference the same variable. ### Use Cases **1. Transactional order confirmation** ```json theme={null} { "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** ```json theme={null} { "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** ```json theme={null} { "vars": { "user_segment": "VIP", "discount_code": "VIP20", "offer_expires": "2024-07-15", "is_first_purchase": true } } ``` In template: ```handlebars theme={null} {{#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. ```handlebars theme={null} {{#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.