Articles in this section

See more

Handlebars Reference: Built-In Merge Tags

Iterable offers several built-in merge tags that you can use anywhere you want to insert dynamic content. No matter how you've set up your data in your project, these merge tags are supported in Iterable templates, snippets, and data feeds.

# In this article

In order to comply with CAN-SPAM laws, you must include an easy way for message recipients to unsubscribe from any marketing message they receive from your brand. Iterable offers several merge tags that you can use to add unsubscribe links to your messages.

If the Auto-append Unsubscribe Block project setting is enabled, Iterable automatically inserts an unsubscribe block, which includes the {{unsubscribeUrl}} merge tag, in email marketing messages. If this setting is disabled, you must include either {{unsubscribeUrl}}, {{unsubscribeMessageTypeUrl}}, or {{hostedUnsubscribeUrl}} in email messages sent through a marketing channel.

To learn more about configuring your project's subscription settings, see Message Channels and Message Types Overview.

NOTE

By default, any merge tags whose names include Url render as raw links when used in a message template. If you want them to render as hyperlinked text, either place the merge tag in an href along with your preferred display text, or use the Insert Link option in the Drag and Drop or WYSIWYG editor to set up your preferred display text and link options.

Using {{unsubscribeUrl}} in the Side by Side editor

Using {{unsubscribeUrl}} in the Drag and Drop editor

# unsubscribeUrl

{{unsubscribeUrl}} inserts a string URL that recipients can click on to unsubscribe from the message channel associated with the message.

# hostedUnsubscribeUrl

{{hostedUnsubscribeUrl}} inserts a string that contains your hosted unsubscribe URL. This merge tag is useful for hosting your own unsubscribe page. To do this, you can create a subscription preference center on your website, and then use the {{hostedUnsubscribeUrl}} merge tag to link to it from your messages.

NOTE

If you want to add tags to the end of your hosted unsubscribe URL, it's best to set them up on your Project Settings page instead of in the body of a message template. However, if you do add the tags in the message template, use & as the first character instead of ?.

To learn more about setting up your hosted unsubscribe URL, see Creating a Subscription Preference Center.

# unsubscribeMessageTypeUrl

{{unsubscribeMessageTypeUrl}} inserts a link that recipients can click to unsubscribe from the message type associated with the message.

# unsubscribeByPhoneUrl

When you use Iterable SMS to send internationally from an alphanumeric sender ID, Iterable includes an unsubscribe link ({{unsubscribeByPhoneUrl}}) in the opt-out instructions. This personalized link takes recipients to a webpage where they can opt out of receiving SMS messages.

You can set up your {{unsubscribeByPhoneUrl}} on your Global SMS Settings page.

To learn more, see SMS Unsubscribes and Resubscribes.

# Campaign metadata

# campaignName

{{campaignName}} inserts the name of the campaign associated with the message.

# campaignId

{{campaignId}} inserts the ID of the campaign associated with the message.

# recurringCampaignId

If the template is associated with a recurring campaign, {{recurringCampaignId}} inserts the name of the parent campaign associated with the message.

# templateName

{{templateName}} inserts the name of the template associated with the message.

# templateId

{{templateId}} inserts the ID of the template associated with the campaign. Iterable automatically generates a unique ID for each template you create.

# clientTemplateId

{{clientTemplateId}} inserts the client ID of the template associated with the campaign. The client ID is a custom identifier that you can set for one or more templates that you create using Iterable's API:

When you update templates with these endpoints, all existing templates in your project with the specified clientTemplateId are updated.

# channelId

{{channelId}} inserts the ID of the message's associated message channel.

# messageTypeId

{{messageTypeId}} inserts the ID of the message's associated message type.

# workflowId

{{workflowId}} inserts the ID of the journey from which the message send was triggered.

NOTE

Journeys were previously called "Workflows" in Iterable. Be sure to use the correct parameter name ({{workflowId}}) to reference journey IDs wherever you use Handlebars in Iterable.

# liveData

Beta Feature

{{liveData}} is currently available as part of the Journey Live Data beta for select Iterable customers. If you're interested in using the feature during beta, reach out to your customer success manager to request access.

In message templates sent from journey campaigns, you can reference data that was fetched by an upstream Live Data journey tile using the following syntax:

{{liveData.objectName.fieldName}}

Replace objectName and fieldName with the actual field names returned by the journey webhook used in your Live Data tile. For example, if your webhook returns an object called product with a field called name, you can reference it as {{liveData.product.name}}.

If you reference {{liveData}} without specifying any subfields, the rendered output includes the entire webhook payload. Test your journey campaign to confirm the data appears as expected.

Before including a {{liveData}} reference in a template, make sure your journey includes a Live Data tile before the message tile. The Live Data tile provides the webhook data that the message can reference at send time—without a preceding Live Data tile, references will render as blank in the final rendered version.

To learn more, see Journey Live Data Overview.

# sendListIds

{{sendListIds}} inserts the audience lists to which the campaign was sent.

TIP

To make the output easier to read, consider using the Handlebars join helper to add a comma between each list ID like this:

{{join sendListIds ","}}

# Your brand details

# brandName

The merge tag {{brandName}} displays your brand's name in the confirmation and legal disclaimer messages for SMS double opt-in message types.

The value for this merge tag is configured in the settings for your SMS double opt-in message type, and can be up to 50 characters long.

Example confirmation message:

{{brandName}}: Reply Y to subscribe to text messages about:
{{messagingInitiative}}

Example legal disclaimer message:

{{brandName}}: Msg & data rates may apply. Msg frequency varies. 
Reply HELP for help, STOP to cancel. Disclaimer: {{smsDisclaimerLink}}

To learn more about SMS Double Opt-In, see SMS Double Opt-In Overview.

# companyName

The merge tag {{companyName}} inserts the name of your project to represent the name of your brand or company when messaging users.

The project's Name field is set in your Project Settings, and displays automatically in the following locations:

  • In default subscription-related pages hosted by Iterable, such as subscribe and unsubscribe success pages.
  • In the default unsubscribe block appended to your emails (if enabled).

# physicalAddress

{{physicalAddress}} inserts your company's physical mailing address. You can set up or edit your company's physical address on your Project Settings page.

You must include a physical address in email messages in order to comply with CAN-SPAM laws. When the Auto-append Unsubscribe Block project setting is enabled, Iterable automatically appends an unsubscribe block in email messages, which includes the physical address from your Project Settings page. If the Auto-append Unsubscribe Block project setting is disabled, you must add {{physicalAddress}} to your unsubscribe code block.

# Recipient details

# email

{{email}} inserts the recipient's email address.

To avoid blank spaces in rendered messages, it's a good idea to include a fallback option in case a recipient's email user profile field is blank or invalid.

# userId

{{userId}} inserts the recipient's user ID.

To avoid blank spaces in rendered messages, it's a good idea to include a fallback option
in case a recipient's userId user profile field is blank or invalid.

# Other

# messagingInitiative

The messaging initiative describes the content associated with a SMS double opt-in message type. It tells your users what kind of content they're subscribing to.

The value for this merge tag is configured in the settings for the SMS double opt-in message type, and can be up to 100 characters long.

Iterable includes this field in the double opt-in confirmation message with the merge tag {{messagingInitiative}}.

Example confirmation message:

{{brandName}}: Reply Y to subscribe to text messages about:
{{messagingInitiative}}

To learn more about SMS Double Opt-In, see SMS Double Opt-In Overview.

# now

{{now}} inserts the current date (generated at send time), in the following format: MMM DD, YYYY (example: Oct 24, 2024)

To learn more about how to use {{now}}, see Handlebars Reference: Date and Time Helpers.

The SMS disclaimer link is a valid URL that begins with https:// and should direct recipients to your brand's terms and conditions or privacy policy.

The value for this merge tag is configured in the settings for the SMS double opt-in message type, and can be up to 100 characters long.

Iterable includes this link in the legal disclaimer message for the SMS double opt-in message type with the merge tag {{smsDisclaimerLink}}.

Example legal disclaimer message:

{{brandName}}: Msg & data rates may apply. Msg frequency varies. 
Reply HELP for help, STOP to cancel. Disclaimer: {{smsDisclaimerLink}}

To learn more about SMS Double Opt-In, see SMS Double Opt-In Overview.

# viewInBrowserUrl

{{viewInBrowserUrl}} inserts a link to a web version of an email message. When you add this to a message template for an email, at send time, it renders as a link recipients can click to view the message in their web browser.

NOTE

When you preview a template that uses locales, the View this email in your browser link in your message proof reflects the template's default locale.

# sendSkip

You can abort a template (and generate a send skip event) using sendSkip. Any send skips originating from this will have a reason of SendAborted. You can pass any additional data you want persisted with the send skip via named parameters.

For example, say your users have a field called creditAvailable, and you want to abort the send if a user doesn't have enough credit to buy some product they're considering. You might do something like:

{{#ifLt creditAvailable product.price}}
  {{sendSkip cause="insufficient credit" creditAvailable=creditAvailable creditRequired=product.price}}
{{/ifLt}}

# Want to learn more?

For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

Iterable Academy

Support docs

Related articles