Variables

Variable System Overview

Variables are placeholders in your templates that get replaced with actual values at render time. They enable personalization without creating separate templates for each recipient.

Variable Syntax

{{variableName|defaultValue}}

Components

• {{ - Opening delimiter
• variableName - The variable identifier
• | - Separator (optional if no default)
• defaultValue - Fallback value (optional)
• }} - Closing delimiter

Examples

Variable Extraction

When you save a template, mailshit extracts all variables:

"Hello {{firstName|there}}, your order {{orderNumber}} shipped!"

Extracts:

• firstName (default: “there”)
• orderNumber (no default)

These appear in:

• The variables panel in the editor
• The grouped variables node in the flow
• The API documentation for that template

Hydration Process

Hydration is replacing variables with values:

Input

Template: "Hello {{firstName|there}}!"
Variables: { "firstName": "Alice" }

Output

"Hello Alice!"

With Default

Template: "Hello {{firstName|there}}!"
Variables: {}

Output

"Hello there!"

Reserved Fields

Fields starting with _ are reserved for system use:

These are not template variables—they’re email configuration.

Don’t use _ prefix in your variable names.

Variable Scope

Variables are scoped to the API request:

{
  "templateId": "tmpl_abc123",
  "variables": {
    "firstName": "Alice",
    "orderNumber": "12345"
  }
}

Each request provides its own variable values.

Variable Types

All variables are strings. For other types:

Numbers

{ "orderTotal": "99.99" }

Dates

{ "orderDate": "January 15, 2026" }

Format dates before sending—templates receive strings.

Lists/HTML

For complex content, pass pre-formatted HTML:

{
  "orderItems": "<ul><li>Item 1</li><li>Item 2</li></ul>"
}

Variable Naming

Good Names

• Descriptive: firstName, orderNumber, trackingUrl
• camelCase: Standard JavaScript convention
• No spaces or special characters

Avoid

• Spaces: first name ❌
• Starting with numbers: 1stName ❌
• Reserved prefix: _subject ❌
• Special characters: first-name ❌

Variables in Different Contexts

Body Text

Hello {{firstName|there}}!

Subject Lines

Your order {{orderNumber}} has shipped

Links

https://example.com/track/{{trackingId}}

Button Text

View {{itemName}}

Image Alt Text

Photo of {{productName}}

Conditional Content

Use variables for optional sections:

{{promoSection|}}

• Pass HTML to show the section
• Pass nothing or empty to hide it

This isn’t true conditionals, but achieves similar results.

Debugging Variables

Variable not replaced?

1. Check spelling (case-sensitive)
2. Verify delimiters: {{ not {
3. Ensure variable is in API request

Seeing raw {{variable}}?

The variable wasn’t provided and has no default:

{{name}}  →  "" (empty)
{{name|default}}  →  "default"

Testing

1. Use the preview panel in the editor
2. Enter test values
3. See rendered result
4. Verify behavior with empty values