newsletter-builder
  • Type to search the documentation.

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

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.

bulk send
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.