Merge Tags and Conditionals

View as Markdown

Merge tags are placeholders that Envoke fills in for each contact when an email is sent. This page lists the tags you can use in your own HTML, how their values are written into the email, and what happens when a tag is misspelled or has no value.

How Merge Tags Work

There are two kinds of tag:

Kind	Looks like	Filled in with
Contact field	`{fname}`	A field of the contact’s record
Envoke tag	`{@brand-address}`, `{@customfield-member_level}`	A custom field, or a value from the message or your account

Tags are replaced when each email is sent, not when the HTML is saved. The stored HTML keeps the tags.
Tags work in the message body and in the subject line.
Write tags exactly as shown on this page, in lower case. Contact-field names must match exactly; Envoke tags are matched without regard to case, but some checks, such as whether your HTML contains an unsubscribe link, look for the lower-case form.
Contact-field and custom-field values are HTML-escaped, so a value containing < or & shows as typed and cannot break your markup.

Contact Fields

Tag	Contact API field	Value
`{fname}`	`first_name`	First name, or your account’s fallback (see below)
`{lname}`	`last_name`	Last name
`{fullname}`	—	First and last name, or your account’s fallback if there is no first name
`{email}`	`email`	Email address
`{title}`	`title`	Title
`{company}`	`company`	Company or organisation
`{phone}`	`phone`	Phone number
`{addr1}`	`address_1`	Address, line 1
`{addr2}`	`address_2`	Address, line 2
`{city}`	`city`	City
`{province}`	`province`	Province or state
`{postal}`	`postal_code`	Postal or ZIP code
`{country}`	`country`	Country code, such as `CA`
`{website}`	`website`	Website
`{language}`	`language`	The language’s name, such as `English` or `French`
`{remote_id}`	`remote_id`	Your own identifier for the contact
`{eid}`	`external_id`	The contact’s external ID, for use in links to your own systems

The fields are described in the Contact API.

First-name fallback. When a contact has no first name, {fname} and {fullname} are replaced with the text in your account’s If first name is missing use setting (Account settings, Email campaigns tab). No other field has a fallback: an empty field is replaced with nothing.
Line breaks in a field’s value become <br> in the email.
Send API messages can use fewer contact fields; see Send API Messages.

Custom Fields

<p>Your member level: {@customfield-member_level}</p>

Form	Example
`{@customfield-NAME}`	`{@customfield-member_level}`
`{@my-NAME}`	`{@my-member_level}`, the form the editor’s merge-field menu inserts
`{@customfield-ID}`	`{@customfield-17}`, using the custom field’s ID

NAME is the custom field’s name, with the same capitalisation. If the field does not exist, or the contact has no value for it, the tag is replaced with nothing.

Option	Effect
(none)	The value, HTML-escaped
`\|html`	The value, HTML-escaped, with line breaks turned into `<br>`. Use for multi-line note fields.
`\|url`	The value, URL-encoded, for use inside a query string: `https://www.example.com/renew?level={@customfield-member_level\|url}`

A custom field holding a full URL can be a link: <a href="{@customfield-renewal_link}">Renew</a>.

Message and Account Tags

Tag	Replaced with
`{@msg-subject}`	The message’s subject, with its own merge tags filled in
`{@msg-url}`	The link to view the message online, personalised for the contact
`{@msg-url\|noeid}`	The view-online link without the contact’s identifier, for sharing
`{@msg-subscription}`	The name of the subscription the message is sent to, in the message’s language, or nothing
`{@msg-mandatory_reason}`	For a mandatory message, its stated reason for being sent; otherwise nothing (see Mandatory Messages)
`{@brand-company}`	Your account’s name
`{@brand-url}`	Your account’s website
`{@brand-address}`	Your account’s postal address, with line breaks (see Your Postal Address)
`{@brand-logo}`	Your account’s logo as an image, linked to your website if one is set
`{@pref-0}`	The link to the contact’s email preferences page, where they can unsubscribe (see Your Unsubscribe Link)
`{@social-NETWORK\|url}`	The link to your profile on that network, from the Social media tab of Account settings. `NETWORK` is one of `facebook`, `twitter`, `linkedin`, `instagram`, `pinterest`, `youtube`, `vimeo`, `rss`, `tripadvisor`, `tiktok`, `bluesky`, `threads`. Without `\|url` the tag is replaced with nothing.

The account name, website, and postal address come from the Account tab of Account settings, and the logo from the Branding tab. For French messages, the account name, website, and logo are the French versions where your account has them.

Tags in Links

Write a link tag as the whole href, with no https:// in front:

<a href="{@pref-0}">Unsubscribe</a>
<a href="{@msg-url}">View this email in your browser</a>
<a href="{@social-linkedin|url}">Follow us on LinkedIn</a>

When click tracking is on, links whose href is a merge tag are tracked like any other link. Contact fields and custom fields can also go inside a link, for example in its query string: https://www.example.com/profile?id={eid}.

Conditionals

A conditional shows content only when a tag has a value:

<p>
{%if @msg-subscription}
  You are receiving this email because you subscribed to {@msg-subscription}.
{%else}
  You are receiving this email from {@brand-company}.
{%endif}
</p>

The syntax is {%if @TAG}, an optional {%else}, and {%endif}, where TAG is a message or account tag from the table above without its braces and @, such as msg-subscription or brand-logo.
The condition is true when the tag’s value is not empty and not 0. There are no comparisons, no “not”, and no “else if”; nest a second {%if} inside {%else} instead.
Options such as |lang:fr are not allowed inside {%if}.
Put a conditional inside an element, such as a <p> or a table cell, never between table tags: browsers, the editor, and Envoke’s send process move text found between table tags out of the table.
Write the keywords exactly: {%if, with no space between { and %.

Send API Messages

Messages sent through the Send API fill in fewer tags, depending on enable_merge_fields:

`enable_merge_fields`	Filled in	Left in the email as written
`false` (the default)	`{@pref-0}`, `{fname}`, `{lname}`, `{eid}`	Every other tag, including `{@brand-address}`
`true`	Every Envoke tag on this page, and the contact fields `{fname}`, `{lname}`, `{fullname}`, `{email}`, `{eid}`, and `{remote_id}`	Nothing; other contact fields are replaced with nothing

Turn enable_merge_fields on whenever your HTML uses any tag other than {@pref-0}, {fname}, {lname}, and {eid}. In particular, with it off, {@brand-address} appears in the email as the literal text {@brand-address}.
With it off, the first-name fallback still applies to {fname}.
Each recipient’s replace values are substituted before the tags are filled in, so with enable_merge_fields on, tags inside a replace value are filled in too.

When a Tag Is Wrong

Nothing checks your tags when the HTML is saved or the message is launched. Send a test to check them (see Test Checklist).

In the HTML	In the email
An unknown or misspelled Envoke tag, such as `{@brand-adress}`	Shown as written
An Envoke tag with an option containing other characters than letters, numbers, `_`, `:`, `,`, `.`, `-`, and spaces	Shown as written
Any other word in single braces, such as `{FNAME}`, `{first_name}`, or a placeholder such as `{SHOW_TITLE}`	Removed: it is looked up as a contact field and, if there is no such field, replaced with nothing
Double braces, such as `{{name}}`	`{}`
`{%if}` with a tag Envoke does not recognise	The whole block, including the `{%if}`, `{%else}`, and `{%endif}`, shown as written; only contact fields inside it are filled in
`{%if}` with an option, a space after `{`, or no closing `{%endif}`	The tags shown as text, and the content of both branches shown

Full reference, OpenAPI description, and Postman collection: developers.envoke.com.