Smart transactional email variables

Email variables in transactional emails are similar to personalization tags that you can add to regular email campaigns. They allow you to personalize your transactional email to include recipient-specific information like customer names, order numbers, account manager details, custom URLs, and more.

Before you start

A smart transactional email can be designed entirely in our email builder, including variables. However, in order for the variables to be replaced with the proper information from your website or application, you'll need a developer to start triggering the emails — if you're not one yourself.

On this page:

How email variables work

A standard email variable in a transactional email is created by placing square brackets around a term, for example: [customer_name] or [order_number]. When the email is sent, the variables are replaced with recipient or event-specific information pulled from your website or application.

Below is a simple example of a transactional email: a restaurant booking confirmation. After a developer has set up the integration with our API, this email will be sent automatically every time someone makes a reservation through the restaurant's website.

In this case the variable information is the guest's name, the day and time requested for the booking, and the number of people dining. The email variables used as placeholder's for that information are:

  • [guest_name]
  • [day]
  • [time]
  • [booking_amount]

When the email is triggered to send, the email variables are replaced with the guest and event details so it arrives in the recipient’s inbox like this:

Naming email variables

You can write whatever you like between the square brackets to create an email variable. The text is just a description of the content that will replace the variable when the email is sent. It doesn’t need to match a field label in your customer database or website.

After you’ve finished creating a transactional email, including email variables, you can always double-check with your developer that everything will work as intended.

Fallback terms

When you insert an email variable using the email builder, as shown in the following section, the square brackets include the term "fallback" followed by an equals sign. A fallback term is a word, or words, that will be substituted in to cover the blanks if you're lacking information about a recipient.

A fallback term can be any plain-text word or phrase. If you can’t think of anything suitable you can leave it blank by writing nothing after the equals sign: [firstname,fallback=]

Or, you can remove the ", fallback=" text completely and just use: [firstname]

Places where email variables can be used

There are multiple places in a smart transactional email where variables can be used.

Subject line

Add one or more email variables to the subject line of your email by clicking Insert email variable on your right:

This will insert a placeholder [variableName, fallback=] at the end of any text already written in the subject line field. Just replace the text inside the square brackets with an email variable name and copy-and-paste it to where you want to use it.

Sender details

Email variables can be used to personalize the "From" name and email address, instead of using a generic sender address like sales@yourcompanyname.

For example, a sales team can set up an email to send to all customers, but personalize it for each recipient using email variables in the "Who is it from?" fields. When the customer receives the email, it appears to be sent from someone they know.

The example below shows email variables used for the "From" name, email address, and the reply-to address, so that any responses will be sent directly to the customer contact.

Tip: Always include a generic "From" name and email address as fallback terms when using email variables to personalize sender details.

Email content

In the email builder, position your cursor anywhere inside a text area to display the editing toolbar. Then click Insert > Email variable to add a [variableName, fallback=] placeholder:


You can also type variables into links. For instance, you could create a button that takes a customer to a tailor-made order tracking page:

Advanced dynamic content

Smart transactional email also supports Liquid, an open-source language created by Shopify to enable dynamic content. While it can be used in a similar fashion to email variables, it enables more advanced things like constructing an inventory list for invoices, formatting text, and showing content based on certain conditions.

You can use standard email variables and Liquid in one transactional email if necessary. However, Liquid is not supported in the "From" name and email fields.

Test your email variables

You don't need the API to send yourself a test version of your smart transactional email. Using our interface, you can send your email to up to five email addresses, with the ability to substitute any variables you've used.

NOTE: If you want to test that your transactional email is correctly grabbing the information from your application or site to replace your variables, you'll need to work with your developer.

Open Transactional, then click on the email name under "Emails". Click View and Edit in the right sidebar, and on the next page at the bottom of the screen, Send a test.

If you've used our standard email variables, you'll see a screen that looks like this:

Enter up to five email addresses to send the test to, making sure to replace the variables with example data, then click Send the test email to see how the final version will look to end users.

If on the other hand you've used the Liquid templating language, you may see a screen that looks like this:

In this instance, if you're not a developer on your application or site, you'll need to talk to them to get the data you require to enter into the "Email Variables" text box.

NOTE: Make sure to also test the plain text version of your email. While we import content from your smart transactional email into the plain text version, you may like to tweak it before sending.