This is part 1 of a 2-part series about personalizing emails with Liquid:
Basic email personalization with Liquid + FAQs —📍You are here!
Personalize emails with your subscribers' first names and more.
Liquid is a template language available for use in your ConvertKit emails. It lets you add dynamic content to your emails, such as a greeting personalized with the subscriber's first name.
Adding names, email addresses, and custom fields
You can add a subscriber’s first name and email address by pasting the following shortcodes into your emails:
{{ subscriber.first_name }}{{ subscriber.email_address }}
But that’s not all!
You can also automatically inject the content of any of your subscribers’ custom fields. Generating the shortcode is simple: use the same format as for the first name and email shortcodes above, but use the name of your custom field instead, and replace any spaces with underscores.
For example:
A custom field called "Last Name" would become
{{ subscriber.last_name }}A custom field called "Photography Experience" would become
{{subscriber.photography_experience }}
☝️ Things to note:
In preview emails, field shortcodes will show up as [FIRST NAME GOES HERE], [EMAIL ADDRESS GOES HERE], etc. This means you've added the shortcodes correctly — those placeholders will be replaced with the actual values once the Broadcast is actually sent out.
In order for custom field shortcodes to work, the name of your custom field must contain only Latin letters, underscores, hyphens, and/or numbers, and must start with a Latin letter or underscore.
To make this process easier, commonly used personalization code snippets are available directly from the email editor!
Click the personalization setting (represented by the @ symbol) from the toolbar at the top of the email editor. Then, select any of the options from the personalization dropdown menu to automatically add the associated shortcode to your email:
NOTE: Curious about that "Subscriber tags conditional" option for displaying conditional content? We go over it in our advanced Liquid guide.
Fallback option
What if your subscriber doesn’t have a first name (or other custom field) value stored in ConvertKit? If you use a shortcode on its own and there’s no value available for that subscriber, it simply won’t render anything.
For example, instead of displaying "Hello [their name]," your email will display "Hello ," instead, with an unnecessary whitespace before the comma.
This is where the fallback option comes in handy! You can use Liquid’s default filter to set it to render different content in place of a custom field value if that custom value isn’t available. Combining it with the strip filter also avoids any extra whitespace.
Here’s an example of how it can be used for first names:
Hello {{ subscriber.first_name | strip | default: "there" }},
In the above code, if the subscriber does have a first name value in your account, it’ll render as “Hello [their name],” whereas if they don’t, it’ll render as “Hello there,” instead.
The code is basically saying to:
Use the
subscriber.first_namevalue if it’s availableBut if it’s not, use the
defaultvalue instead.
In the above example, the word "there" is the fallback content. However, you can modify this to whatever you’d like. For example, to show “Hello friend,” as the fallback instead, the code would be:
Hello {{ subscriber.first_name | strip | default: "friend" }},
☝️ NOTE: Filters (meaning anything that comes after a pipe character, which is that thing that looks like this: | ) are not currently supported in subject lines.
Previewing personalized content
When working with personalized content, you’ll likely want to preview what that content is actually going to render as in the final email. This is possible via our Preview as subscriber feature.
Click the Preview email option on the email editor for your Broadcast or Sequence email:
NOTE: If you're creating a Broadcast, You'll also find a Preview button at the bottom left of your draft Broadcast's Publish page.
After that, click the Preview as subscriber button to double-check how your personalization code will render for a specific subscriber.
Simply start typing any subscriber’s email address in the box, and the drop-down menu will populate with options for you to select from. (If not, refresh your page and try again.)
Once you click one of them, the content in the preview pane will automatically update to show exactly how it’ll look in that particular subscriber’s inbox.
Here’s a demo (notice how the content auto-updates!):
FAQs
Where in ConvertKit can Liquid code be used?
You can use Liquid in these places in ConvertKit:
Broadcast subject lines and email body
Sequence subject lines and email body
Incentive email subject lines and email body
Custom field values in automations (more on this in our advanced guide here)
The only exception is that Liquid filters such as default (i.e., fallback code), truncatewords, capitalize, and strip are currently not supported in subject lines.
Why am I seeing [FIRST NAME GOES HERE] in my preview emails?
Email personalization won't work in preview emails. It'll work in only the actual (i.e., non-preview) email when the email's been sent.
But if your personalized content changes from the Liquid code you see in the email editor to a [SOMETHING GOES HERE] declaration in the preview email, then this means you’ve added the code correctly.
☝️ TIP: Check out the "Previewing personlized content" section above for a great way of test-running your personalized content before it goes out. Alternatively, if you're writing a Broadcast, you can send it to just yourself first as a test!
What does it mean if I'm getting a syntax or merge tag error?
Most often, these errors are due to typos or accidentally misplaced characters. We have a troubleshooting guide here to help you resolve the most common issues we come across!
Looking for more?
This is only the tip of the iceberg! If you're ready to take things a step further and see what else is possible with email personalization, check out our advanced Liquid guide below 👇