Merge tags let your users insert placeholders like into their email templates. When you send the email, your backend replaces these with real values.

Setup

Pass an array of merge tags when initialising or updating the config:

builder.updateConfig({
  mergeTags: [
    { name: 'First name',    value: '{{first_name}}',    sample: 'Jane'       },
    { name: 'Last name',     value: '{{last_name}}',     sample: 'Smith'      },
    { name: 'Company',       value: '{{company}}',       sample: 'Acme Inc.'  },
    { name: 'Unsubscribe',   value: '{{unsubscribe_url}}', sample: 'https://…' },
  ],
});

Field	Type	Description
name	string	Display label shown in the merge tag picker
value	string	The token inserted into the HTML, e.g.
sample	string	Shown in the Preview modal in place of the real token

How it works

When merge tags are configured, a Merge tags toolbar appears inside the rich text editor. Users click a tag to insert it at the cursor position. The token is stored verbatim in the block tree JSON.

In the preview modal, sample values replace tokens so users can see a realistic preview without real data.

Server-side replacement

Before sending the email, replace tokens with real values. Here's a simple Node.js example:

function renderEmail(html, user) {
  return html
    .replace(/{{first_name}}/g, user.firstName)
    .replace(/{{last_name}}/g,  user.lastName)
    .replace(/{{company}}/g,    user.company)
    .replace(/{{unsubscribe_url}}/g, generateUnsubscribeUrl(user.id));
}

const rawHtml  = await builder.compile(template.blockTree);
const finalHtml = renderEmail(rawHtml, currentUser);
await sendgrid.send({ to: currentUser.email, html: finalHtml });

Unsubscribe links

Add a CAN-SPAM/GDPR-compliant unsubscribe footer using the built-in Unsubscribe footer preset in the block palette, or add the tag manually:

{ name: 'Unsubscribe URL', value: '{{unsubscribe_url}}', sample: '#' }

Then generate the URL server-side:

function generateUnsubscribeUrl(userId) {
  const token = jwt.sign({ userId, action: 'unsubscribe' }, process.env.SECRET, { expiresIn: '30d' });
  return `https://yourapp.com/unsubscribe?token=${token}`;
}

Dynamic merge tags

You can update the tag list at any time — useful if the list comes from your API:

// Fetch from your API and hot-update without remounting
const { mergeTags } = await fetch('/api/merge-tags').then(r => r.json());
builder.updateConfig({ mergeTags });