Variables & Theming
Merge tags
Personalise emails with {{variables}}, preview data and per-recipient substitution.
Syntax
Write {{firstName}} in any text, heading, button label, link, subject or preheader. Names may contain letters, numbers, _, - and .. Add a fallback with a pipe: {{firstName|there}}.
variables vs previewData
Two different jobs
- Real runtime values. Applied to the canvas, previews and exported HTML. Use for the current customer, tenant, or fixed values like an unsubscribe URL. Not editable in the UI.
- Sample values for the editor only. Shown in previews but never exported, so an export still contains the original
{{tag}}for your provider to replace.
When both define the same key, variables wins. You can change variables at any time to swap customer data without touching the document.
Per-recipient sending
For large lists, compile once and substitute per recipient. This avoids re-running the compiler thousands of times.
import { compileNewsletter, applyMergeTags } from 'newsletter-builder-react'
const template = compileNewsletter(doc) // tags preserved
for (const person of recipients) {
const html = applyMergeTags(template.html, person.values, { escapeValues: true })
const text = applyMergeTags(template.text, person.values)
await provider.send({ to: person.email, subject: template.subject, html, text })
}Providers have their own syntax (*|FNAME|* for Mailchimp, {{ contact.firstname }} for HubSpot). Use mergeTags with a matching token format, or run a find-and-replace on the compiled HTML before upload.