Table of Contents

Where to start

Smart fields make it easier than ever to personalize your emails. These fields use data from your NationBuilder database to dynamically populate text in your email content. Smart fields help personalize your message by crafting messages that feel 1:1, but can be created once and sent en masse.

Use smart fields to personalize your blast's intro, be specific in your fundraising ask by referencing the last amount someone donated, or send your supporters a personalized recruiter code to share with their networks.

Smart fields exist under the + Add dropdown menu in the Content tab of your email blast. 

Using smart fields

Within the Content area of an email blast:

1. Select + Add > Smart field.

2. A pop up box will appear with all the smart fields you can add to your email blast. Click on the one you wish to use.

3. Click Add smart field.

Your smart field will display within a grey box wherever your cursor was placed in your email content. You can repeat the process to add as many as you wish to an email blast. Make sure to click Save content when finished.

How do I know if all the data exists in a smart field?

Filter for the data ahead of time and include ‘exists’ criteria in the field that you want to use as you are building out your list.

What if a recipient doesn’t have the data for the smart field I am selecting?

If the recipient doesn’t have the data for the smart field, it will either default to whatever exists (if it can’t be in a state with no data) or it appears as blank. The exception to this are a few methods that have a default set by the liquid (first name or friend, full name or friend).

Check out all the blank state fields. The best practice is to make sure the data exists before sending to your list. This can be achieved by filtering. 

Smart fields currently available

What's the difference between smart fields and liquid?

Liquid is the underlying language that powers smart fields to work. Liquid is a templating language that makes it possible to add dynamic content. Liquid must be typed and formatted perfectly to work, as it is a programmatic language. So, smart fields make it easy by allowing you to simply select the field you want from a dropdown menu, no typing or formatting is necessary!

Below you'll find all of the smart fields that are currently available through the menu, and the liquid variable they output "under the hood".

📌 Note: To use smart fields in links (e.g. recruiter links), you will need to hyperlink the URL with the liquid variable. For example www.domain.com/slug?recruiter_id={{recipient.id}}.

Recipient info

Smart Field

Liquid variable

First name or "Friend"

{{recipient.first_name_or_friend}}

Full name or "Friend"

{{recipient.full_name_or_friend}}

Prefix

{{ recipient.prefix }}

First name

{{ recipient.first_name }}

Last name

{{ recipient.last_name }}

Email

{{ recipient.email }}

Home phone

{{ recipient.phone_number }}

Mobile phone

{{ recipient.mobile_number }}

Employer

{{ recipient.employer }}

Occupation

{{ recipient.occupation }}

Precinct name

{{ recipient.precinct_name }}

Social capital amount

{{recipient.social_capital_amount}}

Recipient Primary Address

Smart Field

Liquid variable

Full address

{{ recipient.address.one_line }}

Address 1

{{ recipient.address.address1 }}

Address 2

{{ recipient.address.address2 }}

Address city

{{ recipient.address.city }}

Address state

{{ recipient.address.state }}

Address zip

{{ recipient.address.zip }}

Donations

Smart Field

Liquid variable

Total donation amount

{{recipient.donations_amount_format}}

Last donation amount

{{recipient.last_donation.amount_format}}

Donations year to date

{{recipient.donations_amount_ytd_format}}

Donations count

{{ recipient.donations_count }}

Donation pledge amount

{{recipient.donations_pledged_amount_format}}

Fundraised pledge amount

{{recipient.donations_to_raise_amount_format}}

Fundraised amount

{{recipient.donations_raised_amount_format}}

Memberships

Smart Field

Liquid variable

Newest membership name

{{recipient.most_recent_membership_name}}

Newest membership status

{{recipient.most_recent_membership_status}}

Newest membership expiration date

{{recipient.membership_expires_at}}

Point person

Smart Field

Liquid variable

Point person full name

{{ recipient.parent.full_name }}

Point person phone number:

{{ recipient.parent.phone }}

Point person email

{{ recipient.parent.email }}

Public profile

Smart Field

Liquid variable

Public profile URL

{{recipient.full_profile_url}}

Public profile settings URL

{{recipient.settings_url}}

Recruiter

Smart Field

Liquid variable

Recruiter code

?recruiter_id={{recipient.id}}

Note: you can also copy/paste this liquid to the end of a hyperlink field

Recruits count

{{ recipient.recruits_count }}

Account-level settings

Smart Field

Liquid variable

Primary site URL

{{settings.site.full_url}}

Unsubscribe URL

{{settings.site.unsubscribe_url}}

Organization name

{{ settings.official_name }}

Broadcaster settings

Smart Field

Liquid variable

Broadcaster name

{{ broadcaster.name }}

Broadcaster email

{{ broadcaster.email }}

Broadcaster phone number

{{ broadcaster.phone_number }}

Using custom Liquid markup in email

While smart fields simplify most common in-line content personalization use cases — some situations may call for further customization of the output data, or even special logic to dynamically show/hide blocks of content.

That's why NationBuilder also supports use of raw Liquid template language markup not only within the theme file, but within the email content editor itself. This includes:

  • Output tags for all available signup fields, for situations where we haven't yet created a corresponding smart field, or where you need to use output tag filters to manipulate the data before displaying it to recipients

  • Logic tags, which can be used to wrap blocks of content in conditional IF/ELSE statements, allowing you to dynamically show/hide that content depending on whether or not the recipient meets certain criteria

To add an output tag for any of the signup variables listed here, simply replace the signup prefix with recipient. For example, if you wanted to reference the name of the person who recruited the recipient, you could enter this tag into the editor:

{{ recipient.recruiter.first_name }}

E.g. "We're so happy that {{ recipient.recruiter.first_name }} directed you to us!"

When typing Liquid markup into the email editor, NationBuilder will automatically recognize it, and do it's best to prevent other HTML/CSS style tags from breaking your output/logic tags. In other words, you can safely include spaces after the mustache brackets. Similarly, paragraph breaks before/after a conditional logic tag are ignored.

The following are some example use cases to get you thinking.

Include recipient data inside a hyperlink

Let's say that you wanted to direct people to update their public profile on your website via a hyperlink or button, rather than using a Smart Field to add the full URL into the email body.

To do that, just enter {{recipient.settings_url}} directly into the URL field in the Insert Link or +Add Button windows:

You can similarly append the recipient's personal recruiter code to a URL in those same windows, e.g. if you want to be able to attribute new signups via a share link:

https://twitter.com/intent/tweet?text=Check%20these%20folks%20out!%20https%3A//nationbuilder.com/?recruiter_id={{recipient.id}}

Display custom field values in an email

While it is not yet possible to add custom fields using the Smart Fields menu, you can still add these variables to your emails using the following Liquid tag convention:

{{ recipient.custom_values_for_display['custom_field_slug'] }}

This method is similar to the one described for public profiles here — but again, replacing profile with recipient.

Ask recipient to donate a specific amount over their last donation

Hoping to increase donations? You can do that with the help of a couple Liquid's math output filters. For example, if you wanted to ask the recipient to contribute an amount that's 50% greater than their last donation amount, just enter this tag into the editor:

${{ recipient.last_donation.amount_in_cents | divided_by:100.0 | times:1.5 | round }}

How this output tag works:

  • We start with the last_donation object from the signup variables list, followed by amount_in_cents. This allows us to take advantage of math filters (as opposed to last_donation.amount_format). It does, however, mean that you need to type the currency symbol ahead of the output tag

  • Next, we use the divided_by filter to convert amount_in_cents to dollars.

  • Then we use the times filter to multiply that amount by 1.5 (same as +50%).

  • Finally, we round the result up to the nearest whole number. If you want to keep the cents in there, you could instead use round:2

Conditionally display different calls to action, based on donation history

Want to send one email all of your donors — but adjust just the call to action based on whether the recipient is a small-dollar donor, a mid-tier donor, or a larger donor?

Step one, create three saved filters for each donor tier using the Most Recent Donation Amount criteria (plus whatever other relevant criteria).

And then configure each saved filter to auto add/remove a corresponding Small/Medium/Large Donor tag, as described here.

Now, in the body of your email blasts, you can use Liquid logic to write a simple conditional statement that tells NationBuilder to evaluate which tag the recipient has, then dynamically display a corresponding CTA:

{% if recipient.tags contains "Small Donor" %} 

Will you become a monthly donor at that same level?

{% elsif recipient.tags contains "Medium Donor" %}

Donate this much: ${{ recipient.last_donation.amount_in_cents | divided_by:100.00 | times:1.50 | round }}

{% else %}

Donate this much: ${{ recipient.last_donation.amount_in_cents | divided_by:100.00 | times:1.65 | round }}

{% endif %}

Here's how the above Liquid conditional works:

First it checks to see whether the recipient's list of tags contains the "Small Donor" tag. If yes, it shows the recurring donor ask:

If the don't have that tag, then we check to see if they have the "Medium Donor" tag. If yes, it displays an ask for an amount that's 50% greater than their last donation gift:

This just leaves donors with a "Large Donor" tag, in which case the ask will be for them to donate an amount that's 65% more than their last gift.

Troubleshooting and known limitations

  • If your Liquid markup isn't working as expected, open up the Source Code window, and confirm that no other HTML tags appear within your Liquid tags' surrounding mustache { ... } brackets. If copy/pasting content into the editor from another source (e.g. Google Docs), third-party style tags sometimes get brought over as well, which can break the Liquid code.

  • Currently, it is not possible to use the > nor < comparison operators in Liquid logic tags, as those get converted to escaped HTML. We are looking into fixing this.

Create an email blast

Guide: Email Personalization 101: Liquid, Smart Fields and more

Did this answer your question?