Odyssey – Email Merge Variables
- Bettina Lippisch
In Odyssey, merge variables are used to populate personalized data from your Audience Source files into the emails your audience receives. This allows you to personalize your emails for each individual recipient.
Merge variables become available for use within an Odyssey voyage through the Audience element. When an Audience Source is selected or uploaded, Odyssey will review the fields or columns that are included in the source file or query, and those fields can then be used as merge variables in an Email element.
Merge Variables and Audience Sources
There are three types of Audience Sources that can be used in an Odyssey voyage:
Audience Builder (OnQ)
Internal File
External File
Each Audience Source type, allows Odyssey voyage creators to use standard and custom merge variables within an Email.
Standard Merge Variables
Standard merge variables are available within the Email element for any audience. These merge variables include the following:
Email Name – this populates the recipient’s email address
Track Id – this populates the track Id for the deployment.
Date Merge Variables – this populates the date the email is deployed in the following formats:
Date – M/D/YYYY (Ex. 1/1/2020)
Date – MMDDYYYY (Ex. 01012020)
Date – MMM D, YYYY (Ex. Jan 1, 2020)
Date – Month Name (Ex. January)
Date – Month Numeric (Ex. 1)
Date – Day (Ex. 1)
Date – Year – 2 Digits (Ex. 20)
Date – Year – 4 Digits (Ex. 2020)
Link Merge Variables – this populates a link into your content
Unsubscribe Link with confirmation
Forward to a Friend Link
Online Version
Custom Merge Variables and Audience Builder Sources
Custom merge variables can be used for Audience Builder audience sources via an Output Criteria.
An Output Criteria is the output file specifications for your Audience Builder query when it is output from Audience Builder to Odyssey. To put it simply, the Output Criteria contains the fields Odyssey will use for your audience members.
In the screenshot below, the Select Output Criteria option is displayed.
In the above screenshot, the default Output Criteria is selected and contains the following fields which can be used as Merge Variables in an Email Element:
First Name
Last Name
customer_id
title
company_name
phone
street_1
street_2
city
state_province_code
zip_postal_code
country
encrypted_customer_id
hashed_email_address
email_domain
A custom Output Criteria can also be created and selected so that additional fields can be included as merge variables.
The Output Criteria can be created in Audience Builder by following the steps below.
Create or select a query. For the purpose of creating an Output Criteria, we suggest you use a sample selection of the audience you will use in your voyage.
Select Output > Text File. You may be prompted to save your query before the Output Criteria modal opens.
Leave the default selections, but select Yes in the Save Output Criteria option and provide a name.
Scroll to the Available Fields section and select the fields you would like to include and click Add. Be sure to select at least Customer Id and Email Address. Add in any other fields you’d like to include.
Click the ‘Create Output’ button at the bottom of the modal.
Your Output Criteria will be created and you will receive an email with a link to a text file of the data in your query with the Output Criteria applied.
This criteria can be used within any Voyage within its Profile.
You can modify this criteria by following Steps 1 and 2, above, then selecting your criteria in the Load Output Criteria drop down then selecting Yes in the Save Output Criteria option.
In your voyage, and in any other voyages created within the same profile, the Output Criteria can then be selected within the Audience Element.
This criteria will be used for all Audience Builder files included in your voyage.
Custom Merge Variables and Internal Files
Internal File audience sources are static versions of an Audience Builder query that are saved for use in an Email or Odyssey voyage. After saving, the audience in the file will not change, so consider these a snapshot of your audience whereas an Audience Builder audience source may change over time depending on the conditions in your query.
Custom merge variables can be used for Internal Files by including additional fields when the Internal File is created.
To create an Internal List and specify the fields to include follow the steps below.
Create or select a query. This query will represent the audience that will be included in your Odyssey voyage.
Select Output > Omail File. You may be prompted to save your query before the Output Criteria modal opens.
Select the Deployment Type that will be used to send your email.
Scroll to the field selection section. By default, several fields will already be selected.
Select any additional fields you would like to include and click Add.
Click the ‘Create Output’ button at the bottom of the modal.
Your Internal File will be created and you will receive an email confirming that your file is ready. The Internal File option will be available within the Audience Element when an Email Element is added to the canvas that has the same deployment type as the Internal File.
Custom Merge Variables and External Files
When External Files are uploaded, Odyssey will review the headers included in the file and each header will become available to use as merge variables.
Using Merge Variables in an Email Element
A merge variable can easily be inserted into your content whether you create your Email content via the HTML/Text editor or the Designer.
If creating your content within the HTML or Text editor, select the Merge Variable you’d like to insert within the Insert Merge Variable drop-down and the merge variable will be inserted into your content.
In the Designer, edit or drag a new Text content block into your email. Click ‘Merge Tags’ and select the Merge Tag you’d like to insert.
Note: it is suggested that Merge Variables are inserted using the ‘Insert Merge Variable’ or ‘Merge Tags’ tools, to ensure that the variable will be populated correctly, but merge variables can also be created manually by using the Merge Variable format and the column name.
Using Merge Variable Default Values
When a Merge Variable is inserted into your email content and a recipient has a value present in an audience file for that variable, the value from the file will be populated in the email they receive. If the recipient does not have a value present for the variable, you may want the recipient to see a default value in the email instead.
For example, if you are using the First Name variable in your content, you may want to use “Subscriber” to address the recipient if the audience file is missing their First Name.
Merge Variable Defaults for the Deployment Type
Default Merge Variable values can be set at the Deployment Type level by doing the following:
Navigating to Email Builder > Tools > Deployment Defaults
Scrolling to the Deployment Type section and selecting the Deployment Type
Within the Merge Variable Defaults section, adding the desired Merge Variables and default values.
Merge Variable Defaults for an Email
Default Merge Variable values can also be set within individual emails in an Odyssey voyage. To do so, an applicable merge variable must be included in the HTML or Text version in the Email Element. An applicable merge variable is any variable where a blank value is allowed for the email. This excludes any of the Standard Merge Variables listed above.
When an applicable merge variable is present within the content, and the content is “Applied” within the Email element, a new pleat will appear, “Merge Variable Defaults”.
Each Merge Variable will be listed in the pleat and a default value can be provided. Defaults from the Deployment Type will be prepopulated and can be edited. To refresh the value from the Deployment Type, click the Refresh button. If you’d like the Merge Variable not to populate for recipients if they are missing the value, simply leave the field empty.
Merge Variables and Deployment Reports
Any fields present in an Audience Source file will also be included in the Deployment Delivery reports for any emails in the Voyage. This means you can review the fields included in the Output Criteria for an Audience Builder source or as a column in an External when you review the results of an individual deployment.
Deployment Delivery reports can be accessed through a variety of methods which are listed below.
Deployment Delivery Reports – Email Builder
In Email Builder, click Search and Regular Deployments.
In the ‘Sent As’ drop down, select Odyssey Only.
Find and click the deployment you’d like to review.
Click the link to ‘View Report’.
The Deployment Delivery Report will open and you can review the results of your deployment. Click any number to further review the individual audience members and their values for the fields included in the initial Audience Source file.
Deployment Delivery Reports – Reports & Analytics
From the Reports and Analytics page, select Deployment Delivery Report under Email Reports.
In the ‘Sent As’ drop down, select Odyssey Only.
Find and click the deployment you’d like to review.
Click the link to ‘View Report’.
The Deployment Delivery Report will open and you can review the results of your deployment. Click any number to further review the individual audience members and their values for the fields included in the initial Audience Source file.