Skip to main content

Recipient Fields / Merge Tags

In the Better Email UI, these are now managed as Recipient Fields. During export, those fields become the merge-tag or personalization syntax your ESP expects.

That means the same underlying field can support:

  • personalization in email content
  • dynamic links and short text values
  • segmentation rules
  • integration-specific export syntax

Recipient fields vs. merge tags​

Inside Better Email:

  • Recipient Fields are the fields your team manages in the product
  • Merge tags are the final placeholders exported into the ESP

For example, a field like First name may be shown in Better Email as a reusable recipient field, but export as a different code pattern depending on the integration.

Why they matter​

Recipient fields make personalization and targeting scalable. Instead of hardcoding ESP syntax in every template, you define or sync the field once and let Better Email output the right code for each integration.

How recipient fields work in Better Email​

Each recipient field has a few important properties:

  • a display name for people working in Better Email
  • a key used inside templates and content
  • a data type such as text, number, or boolean
  • an optional integration scope
  • an optional ESP field name override
  • an optional custom insertion code override

You can leave a field global/manual, or scope it to a specific integration when the ESP mapping should only apply in one send context.

In preview mode, Better Email keeps the field readable for the person editing the email. During export, it replaces that placeholder with the correct integration-specific syntax.

TODO: Add a screenshot of the Recipient Fields page showing a mix of manual and synced fields, including type, insertable state, and integration.

Managing recipient fields​

The main management page lives under Recipient Fields.

From there, teams can:

  • add fields manually
  • sync fields from supported integrations
  • filter by type or integration
  • edit field names, keys, and mapping details
  • remove fields they no longer need

Manual fields are useful when you already know the personalization key you need. Synced fields are better when Better Email should mirror the field definitions coming from your ESP.

Adding a field manually​

When you create a recipient field manually, Better Email lets you define:

  1. the display name
  2. the key
  3. the data type
  4. whether the field should be insertable in the editor
  5. whether the field should be global or tied to a specific integration
  6. an optional ESP field name override
  7. optional custom insertion code

If you leave the key blank, Better Email generates one from the name.

If you leave the integration blank, the field stays global. If you choose an integration, the field becomes scoped to that send context.

Syncing recipient fields from an ESP​

Some integrations can sync recipient fields directly into Better Email.

The general flow is:

  1. Open the integration.
  2. Turn on Sync recipient fields.
  3. Save the integration.
  4. Go to Recipient Fields.
  5. Click Sync from <integration name>.

Better Email then creates or updates recipient fields for that integration.

Supported sync details vary by provider. For example:

  • SFMC can sync Contact Builder attribute sets
  • HubSpot can sync contact properties
  • Mailchimp can sync audience merge fields
  • Braze can sync custom attributes

If an integration supports choosing field sources first, do that setup in the integration before running the sync.

TODO: Add a screenshot of an integration settings page with Sync recipient fields enabled and, where relevant, field-source selection visible.

Using recipient fields in the editor​

When a recipient field is marked as Insertable, it can appear in the editor's merge-tag picker and be inserted into supported content areas.

Common uses include:

  • greetings and short text personalization
  • CTA URLs
  • footer or legal values
  • other fields where template authors allow dynamic values

Depending on the input type, template authors can also allow recipient fields inside fields like text strings or links.

Using recipient fields for segments​

Recipient fields are also used to build segmentation rules.

When you create a segment, Better Email lets you choose from the available recipient fields and build rules against them, for example:

  • tier equals gold
  • country equals Denmark
  • loyalty_points greater than 1000
  • language exists

Better Email then renders the matching segment code in the syntax required by the active integration.

This is why keeping recipient fields clean and well named matters. The same field definitions often power both personalization and audience targeting.

TODO: Add a screenshot of the segment builder showing recipient fields being used as the rule inputs.

Best practices​

  • Keep names human-readable so teams can find the right field quickly.
  • Use clear, stable keys.
  • Prefer sync when the ESP is the source of truth for field definitions.
  • Keep a field global only when it truly applies across integrations.
  • Mark fields as insertable only when editors should be able to use them directly.
  • Review exported output in the target ESP before relying on a new field in production.
  • Use recipient fields for true recipient-specific data, not for content that should live in a template setting.