All Collections
Email Templates
Basic email personalization with Liquid + FAQs
Basic email personalization with Liquid + FAQs

How to use Liquid code to personalize emails with your subscribers' first names (and more!), plus frequently asked questions.

Updated over a week ago

This is part 1 of a 2-part series about personalizing emails with Liquid:

  1. 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 allows you to 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 }}, one called ’Photography Experience’ would become {{ subscriber.photography_experience }}, and so on.

☝️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 code to your email:

NOTE: Curious about that conditional content option? We go over it in our advanced Liquid guide here.

Fallback option

What if your subscriber doesn’t have a first name (or other custom field) value recorded 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.

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_name value if it’s available, but if it’s not, to use the default value 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 as follows:

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 a subscriber’ feature.

In the Email menu in the right sidebar of the 'Draft' step of creating a broadcast, you'll see a Preview button:

NOTE: You'll also find a Preview button on the left side of the 'Share' step of creating a broadcast.

The Preview button allows you 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 dropdown will populate with options for you to select from (if not, try refreshing your page and then 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 (note how the content auto-updates!):

☝️TIP: Although this tool is available for only broadcasts at this time, you can still leverage it for sequence content by pasting it into a broadcast draft and proceeding to this page to access the checker. Simply delete the broadcast draft once you've verified your code is working correctly — you can rest assured it'll function the same way in your sequence.


Where can Liquid code be used in ConvertKit?

You can use Liquid in the following places in ConvertKit:

The only exception is that Liquid filters such as default (i.e. fallback code), truncatewords, capitalize, and strip are not currently 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) send. 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 that means you’ve added the code correctly.

☝️TIP: Check out the 'Preview as a subscriber' section above for a great way to test-run your personalized content before it goes out. Alternatively, you can send an actual broadcast to just yourself 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 👇

Did this answer your question?