All Collections
Troubleshooting
Troubleshooting: HTML Email Templates
Troubleshooting: HTML Email Templates

How to resolve common issues with custom email templates built using our HTML editor.

Updated over a week ago

NOTE: This troubleshooting guide is for HTML email templates only. If you created your template using our visual editor, please check out this tutorial instead!

A valid ConvertKit HTML email template requires several key elements that can be easy to overlook, even by experienced coders.

This article will cover several commonly-encountered email template issues, and hopefully help you to identify any troublesome nuances!

Email previews aren't showing any content

Or you're seeing the following error when previewing your template:

Your email template may be missing the {{ message_content }} variable.

This variable is replaced with the content added via the email editor, so it must be included somewhere in your template. More specifically, it must be included where you want your email content to be populated (a common placement is after the header, but before the footer).

Unsubscribe link not working

Or you're seeing the following error when previewing your template:

Your template must have a functioning unsubscribe link to be valid. Since unsubscribe links are generated automatically, they must be added via one of two variables: {{ unsubscribe_link }} or {{ unsubscribe_url }}


These variables look similar, but are very different in how they must be used.

{{ unsubscribe_link }} is the simplest way to add an unsubscribe link in an email: wherever this variable is placed in an email (as-is!), it'll be replaced with the linked word Unsubscribe, which will unsubscribe your subscribers accordingly when clicked.

{{ unsubscribe_url }} is the variable you'll want to use if you want a bit more control over the copy and/or styling of your unsubscribe link. But, unlike its 'link' counterpart, it cannot be used on its own: it must be used as the value of the href attribute for an anchor tag.

Here's an example of correct usage of the {{ unsubscribe_url }} variable:

<a href="{{ unsubscribe_url }}" class="unsubscribe-link">Click here to unsubscribe</a>

You can replace “Click here to unsubscribe” above with any copy of your choice. You can also apply CSS styling to the .unsubscribe-link class to add custom styling to your link, as well!

Physical address requirement is missing

In order to be compliant with anti-spam legislation, all emails sent via ConvertKit must include a physical address at which you can be reached.

As a ConvertKit customer you can use our address if you'd like! We share it, and what you must agree to if you choose to use it, here.


The {{ address }} variable will automatically populate your address as it's entered on this page of your account settings; however, you don't have to use the variable. If you'd like, you can manually add your address to your template by typing it in.

NOTE: Because you have the option to add your address manually, the template preview will not alert you if the {{ address }} variable is missing, like it will the other required components. Please note that it is your responsibility as a ConvertKit sender to ensure all of your emails contain a physical address.

'Update your profile' link not working

NOTE: Adding an 'Update your profile' link is optional — your template can still be valid without one, so long as it includes the {{ message_content }} variable, an unsubscribe link, and a physical address.

Similar to unsubscribe links, the link that allows subscribers to update their own profile is automatically generated. As a result, it must be added via one of the following variables: {{ subscriber_preferences_link }} or {{ subscriber_preferences_url }}

The difference between the use of these two variables is the same as their unsubscribe link counterparts explained above.

Template styling not showing in the email editor

Only our new email editor will display template styling.

If you're using our legacy email editor, you'll have to use the browser and/or email preview buttons in order to see your template's styling applied to your email content.

Still having trouble?

Please reach out to us with a detailed description of your issue (screenshots help, if possible), and the name of the affected template in your account.

PLEASE NOTE: Our support team is limited in how much we can support heavily customized HTML templates, but we will do what we can to recommend the best next steps. For assistance beyond that, we'd recommend posting in our community!

Did this answer your question?