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.

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

1. Basic Email Personalization with Liquid + FAQs — 📍You are here!
2. Advanced Email Personalization with Liquid

---

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 }} and {{ 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 & 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 only contain 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! Just select ‘Personalization’ from the content block menu, and then select any of the options from the modal to automatically add the associated code to your email:

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, including the default filter, 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.

On the last step of creating a broadcast (the ‘Preview’ step), you'll notice this option:

This 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 only available for 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.

FAQs

Where can Liquid code be used in ConvertKit?

You can use Liquid in the following places in ConvertKit:

• Broadcast subject lines & email body
• Sequence subject lines & email body
• Incentive email subject lines & email body
• Content snippets
• Email templates
• 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 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 only work in 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:

Advanced Email Personalization with Liquid

---

Home « Portfolio « ConvertKit Documentation