Overview
Substitution parameters allow you to personalize an email to each guest with minimal work on your part. You simply insert a small bit of code. The code fetches the information from our database, and seamlessly adds it to the email.
Here’s where it is located:
When building an email in the Email Tool, parameters can be accessed in a Text module under the “More” drop-down menu:
Parameters are broken down into four groups as indicated by the four different icons pictured below:
Demographics – this list includes Parameters related to who guests are, e.g. guest first name, favorite store, tier level, date of birth, etc.
Links – these Parameters allow you to insert links that are used in almost every email, e.g. unsubscribe, privacy policy, view email in browser
Wallets – this list includes Parameters related to a guest’s activity, e.g. how many points or rewards they have accrued, how many points or rewards they have remaining, when points and rewards will expire, etc.
Survey – if you created a survey using Survey Center, you can select it from the list to make it appear in the email
Here's how it works:
Let's say you want to address an email to each guest by name. You can't possibly go into every email and add a first name to each email. Instead, you can use a substitution parameter to retrieve the first name associated with each account from the database, and then insert it into each email automatically.
You can do so by selecting “First name” under “Insert Guest Info” in the parameters pop-out:
Here's what that code looks like:
<template:insert field="first_name"></template:insert>
So, instead of starting your email with a generic greeting like, "Hello Guest!", the guest will see "Hello Joe!" in the email.
What if some guests never added a first name when they registered their cards? Or for some reason there's no first name stored in the database. That's awkward, right? No problem. You have a couple options.
1. You can add a default value to use in case the database can't fetch the data:
<template:insert field="first_name">DEFAULT VALUE</template:insert>
<template:insert field="first_name">Guest</template:insert>
A guest with a first name in the database will see: Hello Joe!
A guest with no info in the database will see: Hello Guest!
Here is where you enter the chosen default value:
This is what you’ll see in the Preview Pane when you add this Parameter (including Default text) to your message:
2. If you don't add a default value, there won't be any extra space between the leading text (Hello) and punctuation (!); the guest won't necessarily notice that anything is missing:
A guest with a first name in the database will see: Hello Joe!
A guest with no info in the database will see: Hello!
You'll need to use your best judgment on whether you need a default value or not. In some cases, your email may not make logical sense without one. A couple examples include: a promo expiration date, including the number of points or rewards a guest has, or has just earned. For example, if you want to let guests know how close they are to their next reward, you might write something like "Congrats, 40 points until your next reward!" (where 40 is pulled in via a substitution parameter). Without a default value, a guest would see "Congrats only points until your next reward!" In that case you might want to think about a version of that statement that can accommodate both specific data, and a default value. Something like:
A guest with a balance in the database will see: Congrats! You're 40 points to your next reward!
A guest with no info in the database will see: Congrats! You're so close to your next reward!
**In this example, "40 points" comes from two separate substitution parameters: wallet balance(40), and wallet label ("points"). To get the generic version, you'd set a default value of "so close" for the wallet balance parameter, and no default value for the wallet label parameter.
Before You Start
Generally speaking, almost any data we store within a guest account can be pulled into an email via a substitution parameter. We've curated a few lists of the most heavily-used parameters. If you ever have any questions about personalizing an email in a way not listed here, please email [email protected].
Parameter Lists
Most Common Parameters
The chart below contains the most commonly used parameters. Some of these commonly used parameters are one-off use cases. For example, you may use a guest's full name, and complete address when confirming a loyalty card registration, but after that you probably won't use those parameters much. It's pretty rare to use those parameters in bulk emails for promotions.
Then, there are the parameters used by many clients, and often: first name, wallet balances, and guest activity. These parameters are inbold typein the Data column to help you spot them easily. For these parameters, we've included a sample of how the parameter might appear in an actual email, once data has been pulled in (via the parameter). In these examples, the text that would be pulled in via the parameter is inbold and underlined type- it won't actually appear in bold/underline way in emails to guests (unless you format it that way).
Parameters - Demographics
Data | Parameter | What it looks like in a guest email |
address 1 | <template:insert field="address1"></template:insert> |
|
address 2 | <template:insert field="address2"></template:insert> |
|
card number | <template:insert field="card_number"></template:insert> |
|
card registration code | <template:insert field="card_regcode"></template:insert> |
|
card template | <template:insert field="card_template"></template:insert> | Thanks for joining our Preferred Guest Program. |
city of residence | <template:insert field="city"></template:insert> |
|
country abbreviation | <template:insert field="country_short"></template:insert> |
|
country name | <template:insert field="country_long"></template:insert> |
|
date email sent | <template:insert field="date_email_sent"> </template:insert> |
|
date of birth | <template:insert field="date_of_birth"> </template:insert> |
|
email address | <template:insert field="email"> </template:insert> |
|
enrollment store code | <template:insert field="enroll_store_code">participating |
|
enrollment store name | <template:insert field="enroll_store_name">participating | Thanks for picking up a card at our Assembly Square location. |
favorite store address | <template:insert field="favorite_store_address1"></template:insert> |
|
favorite store city | <template:insert field="favorite_store_city"></template:insert> |
|
favorite store hours of operation | <template:insert field="favorite_store_hours"></template:insert> |
|
favorite store name | <template:insert field="favorite_store_name">any location | Join us at Riverside for Taco Tuesday! |
favorite store phone | <template:insert field="favorite_store_phone"></template:insert> |
|
favorite store state long | <template:insert field="favorite_store_state_long"></template:insert> |
|
favorite store state short | <template:insert field="favorite_store_state_short"></template:insert> |
|
favorite store ZIP | <template:insert field="favorite_store_zip"></template:insert> |
|
first name | <template:insert field="first_name">Friend</template:insert> | Hello Joe! |
last name | <template:insert field="last_name"></template:insert> |
|
mobile phone number | <template:insert field="mobile_phone"></template:insert> |
|
phone number | <template:insert field="phone"></template:insert> |
|
postal code/ZIP | <template:insert field="postal_code"></template:insert> |
|
salutation | <template:insert field="salutation"></template:insert> |
|
state/province abbreviation | <template:insert field="state_short"></template:insert> |
|
state/province name | <template:insert field="state_long"></template:insert> |
|
subscription amount charged | <template:insert field="subscription_amount_charged"></template:insert> |
|
subscription end date | <template:insert field="subscription_end_date"></template:insert> |
|
tier label | <template:insert field="tier_label"></template:insert> |
|
username | <template:insert field="username"></template:insert> |
|
Parameters - Links
These parameters simply insert a commonly-used link into your email. The first two are generally required in all emails you send. You may want to offer a "view in email browser" option if your email contains HTML, or relies heavily on images. These parameters insert clickable descriptive text ("click here") that, when clicked, re-direct the guest to the correct URL. They're helpful because it means you don't have to remember the URL, or type plain text and then attach the correct URL to it.
Data | Parameter | What it looks like in a guest email |
privacy policy | <template:link type="px_privacy_url">Click here to view our privacy policy</template:link> | Privacy Policy |
unsubscribe | <template:link type="unsubscribe_url">Click here to unsubscribe</template:link> | Click here to unsubscribe |
view email in browser | <template:link type="campaign_view_url">If you are having trouble viewing this email, click here</template:link> | If you are having trouble viewing this email, click here (This will appear as clickable text that re-directs the guest to a web browser to view the email) |
Parameters - Wallets (Rewards, Points, Balances, Expiration Dates, etc.)
Important notes:
Wallet-based parameters are usually used for transactional emails (emails triggered by a specific guest activity - visit, purchase of a specific item, reward earned, etc.) rather than in bulk emails associated with a promotional campaign.
A wallet stores information about a guest transaction. A single transaction will often affect multiple wallets. For example, if a guest visits, buys coffee and a sandwich, and spends a total $10.32, we may adjust 4 wallets based on that one transaction:
1 visit (added to the "visits" wallet)
1 coffee (added to the "coffees bought" wallet)
1 sandwich (added to the "sandwiches bought" wallet)
$10.32 (added to the "guest spend per visit" wallet)
Each wallet has its own wallet code. When using a wallet parameter to provide info to a guest about the balance or activity in a wallet, you'll need to specify which wallet by using the wallet code. If you don't know which wallet code to use, a Technology Consultant can assist you.
Often, you will need to use wallet label in combination with most of the other wallet parameters. When you are giving guests information about the balance, or transaction history of a particular wallet, you'll need both count/content of the wallet ("1") and the wallet label ("free pizza") to give complete info to the guest. Wallet code will automatically populate when you select the wallet in the parameter section.
Data | Parameter | What it looks like in a guest email |
wallet balance | <template:insert field="wallet_balance(walletcode)"></template:insert> | You've got 40 points to use! |
wallet label | <template:insert field="wallet_label(walletcode)"></template:insert> | You've earned a free pizza! |
wallet label long | <template:insert field="wallet_label_long(walletcode)"></template:insert> |
|
wallet label short | <template:insert field="wallet_label_short(walletcode)"></template:insert> |
|
wallet label tiny | <template:insert field="wallet_label_tiny(walletcode)"></template:insert> |
|
next wallet expiration short | <template:insert field="wallet_expiration_short(walletcode)"></template:insert> |
|
next wallet expiration long | <template:insert field="wallet_expiration_long(walletcode)"></template:insert> |
|
Parameters - Survey
These parameters simply insert a commonly-used link into your email. The first two are generally required in all emails you send. You may want to offer a "view in email browser" option if your email contains HTML, or relies heavily on images. These parameters insert clickable descriptive text ("click here") that, when clicked, re-direct the guest to the correct URL. They're helpful because it means you don't have to remember the URL, or type plain text and then attach the correct URL to it.
Less Common Parameters
These parameters may be helpful depending on your program, or for specific types of promotions/campaigns. We recommend emailing [email protected] prior to using them.
Data | Parameter |
custom question 1 | <template:insert field="custom_question_1"></template:insert> |
custom question 2 | <template:insert field="custom_question_2"></template:insert> |
custom question 3 | <template:insert field="custom_question_3"></template:insert> |
custom question 4 | <template:insert field="custom_question_4"></template:insert> |
custom question 5 | <template:insert field="custom_question_5"></template:insert> |
custom question 6 | <template:insert field="custom_question_6"></template:insert> |
For further assistance, please contact your solutions consultant or customer success manager, or email [email protected].