Skip to main content

Template Syntax

MessagePipe uses Handlebars templating engine with custom helpers for dynamic content generation. This allows you to create messages with conditional logic, loops and formatting.

Basic Variable Substitution​

The simplest form of templating is variable substitution using double curly braces:

Hello {{firstName}}! Your email address is {{user.email}}.

Variables object:

{
  "firstName": "John",
  "user": {
    "email": "john@example.com"
  }
}

Result:

Hello John!

Your email address is john@example.com.

Built-in Helpers​

MessagePipe provides several built-in helpers for common formatting and logic operations.

Text Formatting Helpers​

uppercase​

Converts text to uppercase:

Hello {{uppercase firstName}}!
Hello JOHN!

lowercase​

Converts text to lowercase:

Your username is {{lowercase username}}.

capitalize​

Capitalizes the first letter:

Welcome {{capitalize firstName}}!
Welcome John!

default​

Provides a fallback value if the variable is empty or undefined:

Hello {{default firstName "Valued Customer"}}!

If firstName is empty or undefined, outputs: Hello Valued Customer!

Date Formatting Helper​

formatDate​

Formats dates in various formats:

{{formatDate createdAt "YYYY-MM-DD"}}
<!-- 2024-01-15 -->
{{formatDate createdAt "MM/DD/YYYY"}}
<!-- 01/15/2024 -->
{{formatDate createdAt}}
<!-- Default locale format -->

Supported formats:

  • YYYY-MM-DD - ISO date format
  • MM/DD/YYYY - US date format
  • Default - Browser locale format

Conditional Helpers​

ifEquals​

Display content only if two values are equal:

{{#ifEquals user.status "premium"}}
  <div class="premium-banner">
    <h2>Premium Member Benefits</h2>
    <p>Enjoy exclusive features!</p>
  </div>
{{else}}
  <p>Upgrade to premium for more features!</p>
{{/ifEquals}}

ifNotEquals​

Display content only if two values are NOT equal:

{{#ifNotEquals user.role "admin"}}
  <p>This content is for non-admin users.</p>
{{/ifNotEquals}}

Standard Handlebars Features​

MessagePipe supports all standard Handlebars functionality:

Loops with each​

<h3>Your Recent Orders:</h3>
<ul>
  {{#each orders}}
    <li>
      Order #{{this.id}}
      -
      {{formatDate this.date "MM/DD/YYYY"}}
      ({{uppercase this.status}})
    </li>
  {{/each}}
</ul>

Variables:

{
  "orders": [
    { "id": "12345", "date": "2024-01-15T10:30:00Z", "status": "shipped" },
    { "id": "12346", "date": "2024-01-10T14:20:00Z", "status": "delivered" }
  ]
}

Conditional Blocks with if​

{{#if user.hasSubscription}}
  <p>Your subscription is active until
    {{formatDate user.subscriptionEnd "MM/DD/YYYY"}}.</p>
{{else}}
  <p>You don't have an active subscription.</p>
{{/if}}

Nested Object Access​

Welcome
{{user.profile.firstName}}
{{user.profile.lastName}}! Your company:
{{user.company.name}}
Address:
{{user.company.address.street}},
{{user.company.address.city}}

Complete Email Template Example​

<!DOCTYPE html>
<html>
  <head>
    <title>Welcome to {{companyName}}</title>
    <style>
      .premium {
        background: linear-gradient(45deg, gold, orange);
        padding: 20px;
      }
      .basic {
        background: #f5f5f5;
        padding: 15px;
      }
    </style>
  </head>
  <body>
    <h1>Welcome {{capitalize firstName}}!</h1>

    <p>
      Thanks for joining {{companyName}} on {{formatDate signupDate
      "MM/DD/YYYY"}}.
    </p>

    {{#ifEquals accountType "premium"}}
    <div class="premium">
      <h2>Premium Member Benefits</h2>
      <ul>
        {{#each premiumFeatures}}
        <li>{{this}}</li>
        {{/each}}
      </ul>
    </div>
    {{else}}
    <div class="basic">
      <h2>Getting Started</h2>
      <p>
        Here's what you can do with your {{capitalize accountType}} account:
      </p>
      <ul>
        {{#each basicFeatures}}
        <li>{{this}}</li>
        {{/each}}
      </ul>
    </div>
    {{/ifEquals}} {{#if hasOrderHistory}}
    <h3>Your Recent Activity</h3>
    <ul>
      {{#each recentOrders}}
      <li>{{this.item}} - {{formatDate this.date "MM/DD/YYYY"}}</li>
      {{/each}}
    </ul>
    {{/if}}

    <hr />
    <p>
      Best regards,<br />
      {{default senderName "The Team"}}<br />
      {{companyName}}
    </p>
  </body>
</html>

SMS Template Example​

SMS templates are simpler but support all the same helpers:

Hi
{{capitalize firstName}}!

{{#ifEquals messageType "verification"}}
  Your verification code is
  {{code}}.
{{else}}
  {{#ifEquals messageType "reminder"}}
    Reminder: Your appointment is
    {{formatDate appointmentDate "MM/DD"}}
    at
    {{time}}.
  {{else}}
    Thanks for using
    {{companyName}}!
    {{message}}
  {{/ifEquals}}
{{/ifEquals}}

Reply STOP to opt out.

Best Practices​

Always Provide Defaults​

<!-- Good -->
Hello
{{default firstName "Valued Customer"}}!

<!-- Avoid -->
Hello
{{firstName}}!

Safe Property Access​

<!-- Good -->
{{#if user.profile}}
  Welcome
  {{user.profile.name}}!
{{/if}}

<!-- Avoid -->
Welcome
{{user.profile.name}}!

Use Semantic Helpers​

<!-- Good -->
{{#ifEquals status "active"}}
  Your account is active.
{{/ifEquals}}

<!-- Less readable -->
{{#if isActive}}
  Your account is active.
{{/if}}

Keep SMS Templates Concise​

<!-- Good - concise -->
Hi
{{name}}! Your code:
{{code}}. Expires in 10min.

<!-- Too long -->
Hello
{{firstName}}, your verification code is
{{code}}. Please enter this code within the next 10 minutes or it will expire.

Testing Templates​

Preview Template​

Use the preview endpoint to test your template with sample data:

curl -X POST "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/templates/preview" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "your-template-id",
    "variables": {
      "firstName": "John",
      "companyName": "Nobu",
      "signupDate": "2024-01-15T10:30:00Z"
    }
  }'

Extract Variables​

Get a list of all variables used in a template:

curl -X GET "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/templates/variables/your-template-id" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Returns:

["firstName", "companyName", "signupDate", "accountType"]

Common Template Errors​

Invalid Handlebars Syntax​

{
  "statusCode": 400,
  "message": "Template rendering error: Parse error on line 5",
  "error": "Bad Request"
}

Solution: Check for unmatched {{#if}} blocks, missing {{/each}} closers, etc.