Liquid variables available in email

NationBuilder is alpha-testing the availability of all signup, broadcaster, and mailing liquid variables in email blasts and autoresponse emails. These variables can be used in the subject line and body copy of email blasts and autoresponse emails. This works differently than creating webpages. Whereas liquid must be placed in the template of a webpage, it can be used within the WYSIWYG editor of emails.

When including a liquid variable in an email blast, the recipient prefix will be needed where the signup prefix is used in a webpage. For example, to include a person's first name:

{{ signup.first_name}} is used on a page

{{recipient.first_name}} is used in an email blast or autoresponse email

When copy/pasting liquid into the WYSIWYG editor, be sure that you either the right-click in the editor and select the "paste and match style" command, or click the "paste as plain text" button on the editor itself. Utilizing the standard cmd/ctrl+v or right click + paste methods is likely to introduce stray < span > and < p > tags, which will prevent the liquid from rendering.

Please use the liquid in email feedback form if you have comments on how the feature is currently working. Note that alpha-testing means that we have several additional changes planned before the feature will be fully supported. We are beginning to develop documentation for using liquid variables in email, as seen below. Complete support information will be available once alpha and beta testing are completed.


Brief overview of liquid functions

Logic tags

Logic tags indicate programming logic. These statements begin with things like if, for, and unless. {% open conditionals and %} close them. Statements must be completed with an ending tag.

  • {% if %} must be completed with {% endif %}
  • {% for %} must be completed with {% endfor %}
  • {% unless %} must be completed with {% endless %}

Statements can be modified before they are completed. Modifiers do not need closing tags.

  • {% else %} displays what happens when the original condition is not true.
  • {% elsif %} displays what happens when the original condition is not true and another condition is true. This lets you add another specific condition as part of the original statement.

Example if statement: If recipient is a donor, display this content.

Example modified if statement: If recipient's first name is Brandt, display this content. Otherwise, display different content.

Comparison and logic operators

Operators allow you to compare liquid variables within the logic tags, including equal, not equal, and greater than.

With dollar amounts, using equal (==) will only match transactions of the exact amount stated. You will probably use the greater than or equal to (>=) and less than or equal to (<=) operators more frequently than (==). Please note that the < and > comparison operaters do not work within the WYSIWYG editor, and must be placed in the HTML Template of the email theme in question.

Output tags

Output tags display information based on the variable contained within the tags. They are surrounded by {{ two curly brackets }}.

For example, {{ recipient.first_name }} will display the first name of the profile receiving the email.


Examples of using liquid in email

Insert recipient's name in subject line

A recipient's name can be added to an email subject line or the body of an email. If your recipient list includes profiles that are missing name information, you can use an if statement to remove or replace the name with something else.

Subject line desired: Cynthia, welcome to the organization! Alternative: Welcome to the organization! This displays the recipient's first name if the field contains more than one character, which avoids sending a personalized subject line to first initials, while allowing "CJ" to receive an email addressed to her.


Send different content based on location

In this example, the filter is based on the state a person lives in. This example assumes your data contains a combination of codes (CA) and complete words (California). "Contains" checks to see if the variable attribute contains those characters. "CA" will match to CA, Southern California, and California.

If you know your data only includes state information as two-letter codes, you can use an equal statement.


Display custom fields in an email

Custom people field values can be displayed via Liquid using the "custom_values_for_display" variable. For example, the following will return all of the custom field values for the recipient of the email:

It's also possible to display a specific custom field by scoping the output to its associated slug:

The ability to display custom donation values in email is limited but available. See How to display custom donation fields in email for more information.

As a reminder, please use the liquid in email feedback form if you have comments on how the feature is currently working.


Customize your default salutation

While all new email blasts include the {{ recipient.first_name_or_friend }} in the body by default, you might want to customize this salutation to use a word other than "Friend". Liquid's `default` filter is perfect for this instance, because it displays a custom phrase whenever the output would otherwise be blank. In the following example, if the user profile in the database did not have a first name, they'd see the word "Supporter"


Known limitations to liquid in email

Because email blasts operate independently from any particular site in your nation, the {{ recipient.settings_url }} and {{ recipient.full_profile_url }} variables will not work in email blasts. Instead, you can recreate these variables by hardcoding part of the URL. The following example shows how you could recreate the {{ recipient.settings_url }} variable in this way:


Additionally, "<" and ">" comparison signs cannot be used in liquid tags in email to compare values. The way that these symbols are encoded by the text editor prevents them from working in liquid tags. However, they will work in liquid tags if they are placed in the template of a custom email theme.


How to set up an email blast

Signup liquid variables

Broadcaster liquid variables

Mailing liquid variables

Liquid in email feedback

How to create and use custom people fields

If you’re unclear on how this feature works, please ask a question. If you would like to see changes to this feature, please submit a suggestion.