Templating

Buttondown uses a templating language to mix programming code into plain old HTML. By adding logic and variables to your email you can customize your content per-subscriber, or to repeat structures in your email without having to hand code them multiple times.

Variables allow you to programmatically add text to your email. You may have previously worked with variables in the form of "mail merges".

Variables are wrapped in double curly braces. Here's how this looks:

{{ variable }}

Like a mail merge, the variable code is replaced with the correct text when an email is sent out. For example, if you wanted to add a personalized greeting to your email, it might look like this:

Check out our article on metadata to learn what's possible!

Filters are tools that you can use to modify the output of a variable. This uses the same double curly brace syntax, but the variable name is followed by a pipe and the filter you'd like to use.

For example, if you wanted to make sure your email subject line was always capitalized, you could add the capfirst filter, like so:

{{ email.subject|capfirst }}

As Buttondown's templating language is built on Django you can use any of their available filters.

Tags are bits of code that are added to your HTML content that can do all sorts of things, including logic!

Tags are wrapped in a single curly brace and a percentage sign, and look like this:

{% tag %}

The for and if else loops should cover most use cases in Buttondown.

If you want to send a weekly digest of all your blog posts, you could iterate over the list of these items with a for loop:

{% for email in emails %}
    <h2>{{ email.title }}</h2>
    <p><a href="{{ email.absolute_url }}">Read more</a></p>
{% endfor %}

You might want to also be able to access a counter for each iteration. You can do this by using the forloop object. Here's how you could use it to add a number to each blog post:

{% for email in emails %}
    <h2>{{ forloop.counter }}. {{ email.title }}</h2>
    <p><a href="{{ email.absolute_url }}">Read more</a></p>
{% endfor %}

If you wanted to send your premium subscribers a special message you could use an if/else loop, like this:

{% if subscriber.subscriber_type == 'premium' %}
    Thanks for being a paid subscriber!
{% else %}
    Thanks for reading!
{% endif %}.

You could also use elif (else if) tags to send different messages to your premium subscribers, free subscribers, and non-subscribers. Here's how this would look:

{% if subscriber.subscriber_type == 'premium' %}
    Thanks for being a paid subscriber!
{% elif subscriber.subscriber_type == 'regular' %}
   Want to support my writing? <a href="{{ premium_subscribe_url }}">Upgrade now!</a>
{% else %}
    Like what you read? <a href="{{ subscribe_url }}">Subscribe now!</a>
{% endif %}.

Have a situation that needs something more than a for or if else loop? Fear not! There are lots of other pre-built tags on the Django site.

• The absolute URL of the email you're sending out.
• email.url is an alias for email.absolute_url and works the same way (use email.absolute_url in new templates).

• A boolean indicating whether the email is being sent to a premium subscriber.

• The raw date time of the email being sent out.

• The issue number of the email being sent out.

• The subject of the email you're sending out.
• The subject length is limited to 2000 characters.

• A link that allows subscribers to change the data configured as subscribe form inputs. This requires the Portal to be enabled.

• Either 'email' (for emails) or 'web' (for web views).

• A link to prompt existing free subscribers to upgrade. (Only relevant for paid newsletters.) This is the exact same thing as upgrade_url.

• A random number between two values for things like A/B testing.

• An embedded subscribe form for your newsletter, just like the one that appears at the bottom of your archives.
• This only appears on the web/archive version of your email; it will not appear in the actual emails sent to subscribers.

• A generic URL for your subscription page.

• Whether or not a subscriber is able to be upsold to a paid subscription.

• A boolean that is true if the subscriber is on a paid plan and false if they are not.

• Access to the email address for a given subscriber.

• The unique ID for a given subscriber.

• Access to the metadata for a given subscriber.

• Access to the subscriber type (premium, regular, etc) for a given subscriber.

• Access to the tag names of a given subscriber.

• A personalized URL for the given subscriber to unsubscribe with.

• A link to prompt existing free subscribers to upgrade. (Only relevant for paid newsletters.)