Merge Tags

Merge tags are placeholder variables in your email templates that get replaced with real data when the email is sent. For example, {{first_name}} might become "Jane" for one recipient and "Alex" for another.

The Templatical SDK detects merge tags in template content and displays them as friendly labels in the editor, so your users see "First Name" instead of raw {{first_name}} syntax.

Configuration

Pass merge tags through the mergeTags option in init():

const editor = await init({
  container: '#email-editor',
  auth: { url: 'https://your-app.com/api/token' },
  mergeTags: {
    tags: [
      { label: 'First Name', value: '{{first_name}}' },
      { label: 'Last Name', value: '{{last_name}}' },
      { label: 'Email', value: '{{email}}' },
      { label: 'Unsubscribe URL', value: '{{unsubscribe_url}}' },
    ],
  },
});

Each tag has:

Property	Type	Description
label	string	Display name shown in the editor
value	string	The merge tag string to match in template content

Supported Syntaxes

Different email platforms use different merge tag syntax. The SDK supports 5 built-in presets and custom patterns.

Built-in Presets

Preset	Value Tags	Logic Tags	Platforms
liquid (default)	{{variable}}	{% if %} ... {% endif %}	Liquid, Jekyll, Shopify, Twig
handlebars	{{variable}} or {{{variable}}}	{{#if}} ... {{/if}}	Handlebars, Mustache, Ember
mailchimp	*|VARIABLE|*	*|IF:CONDITION|* ... *|END:IF|*	Mailchimp, Mandrill
ampscript	%%=variable=%%	%%[IF ...]%% ... %%[ENDIF]%%	Salesforce Marketing Cloud
django	{{variable}}	{% if %} ... {% endif %}	Django, Jinja2

Using a Preset

mergeTags: {
  syntax: 'mailchimp',
  tags: [
    { label: 'First Name', value: '*|FNAME|*' },
    { label: 'Last Name', value: '*|LNAME|*' },
    { label: 'Email', value: '*|EMAIL|*' },
  ],
},

Custom Syntax

If your platform uses a syntax not covered by the presets, pass a custom object with value and logic regex patterns:

mergeTags: {
  syntax: {
    value: /\$\{.+?\}/g,       // Matches ${variable}
    logic: /\$\{#(\w+).*?\}/g, // Matches ${#if ...}
  },
  tags: [
    { label: 'First Name', value: '${first_name}' },
    { label: 'Company', value: '${company}' },
  ],
},

Property	Type	Description

| value | RegExp | Pattern to detect value merge tags (e.g., {{name}}) | | logic | RegExp | Pattern to detect logic merge tags — group 1 must capture the keyword (e.g., if, endif) |

Both patterns must use the global flag (/g).

How Merge Tags Appear in the Editor

Value Tags

When a configured merge tag value is found in template content, the editor replaces the raw syntax with a styled chip showing the label. For example, {{first_name}} appears as a labeled badge reading "First Name".

Logic Tags

Logic tags (conditionals like {% if %} or {{#if}}) appear as keyword badges showing the detected keyword (e.g., "if", "endif", "else"). These are detected using the syntax.logic pattern.

Dynamic Merge Tag Picker

For applications with many or dynamic merge tags, use the onRequestMergeTag callback instead of (or in addition to) a static tags list. This lets you show your own picker UI:

const editor = await init({
  container: '#email-editor',
  auth: { url: 'https://your-app.com/api/token' },
  mergeTags: {
    syntax: 'liquid',
    tags: [], // Can be empty when using dynamic picker
  },
  onRequestMergeTag: async () => {
    // Show your own merge tag picker (modal, dropdown, etc.)
    const selected = await showMergeTagPicker();

    if (!selected) {
      return null; // User cancelled
    }

    return {
      label: selected.name,     // e.g., "First Name"
      value: selected.mergeTag, // e.g., "{{first_name}}"
    };
  },
});

The callback is triggered when the user clicks the merge tag button in the text toolbar. It must return a MergeTag object ({ label, value }) or null if the user cancels.

Use Cases

• Personalization — Greet recipients by name, reference their company, or include account-specific details
• Dynamic URLs — Insert unique links like unsubscribe URLs, profile pages, or tracking links
• Conditional greetings — Use logic tags to show different content based on recipient data (see also Display Conditions)
• E-commerce — Insert order details, product recommendations, or loyalty program status

Best Practices

• Use descriptive labels — "Customer First Name" is clearer than "fname" for your users
• Match your sending platform's syntax — Choose the preset that matches your email sending service (e.g., 'mailchimp' for Mailchimp)
• Include all commonly used tags — The more tags you configure, the better the editor experience
• Consider the dynamic picker for large tag sets — If you have dozens of merge tags, use onRequestMergeTag with a searchable modal instead of a long static list