RSS-to-email

If you're a blogger, podcaster, or other content creator, you probably already know that RSS is a great way to distribute your content. But did you know that RSS can also be a great way to automate your newsletter?

With Buttondown's RSS automation, you can automatically send your subscribers a new email every time you publish a new blog post, podcast episode, or other piece of content. You can even schedule your emails to go out weekly or monthly, if you prefer.

This is a great solution for creators who already have their content published on the web (either through a CMS like Wordpress, a static site generator such as Jekyll or Gatsby, or a JAMStack site), but don't want to spend time manually creating and sending a newsletter every time they publish something new.

You can create an RSS automation in Settings > Basic > RSS-to-email.

At the moment, you can choose from three different 'cadences' for your RSS automation:

• You can have trigger a new email every time a new item is published in your RSS feed. (Buttondown checks your RSS feed every thirty minutes, so it's not quite instantaneous.)
• You can trigger a new email every week, on a day and time of your choosing.
• You can trigger a new email every month, on a day and time of your choosing.

(Note that for the weekly and monthly cadences, Buttondown's automation will only trigger if there's a new item in your RSS feed.)

You can choose from two different behaviors for your RSS automation that trigger according to the above cadence:

• You can have Buttondown send a new email every time a new item is published in your RSS feed.
• You can have Buttondown create a new draft email every time a new item is published in your RSS feed.

The difference between these two behaviors is that the first will send the email immediately, while the second will create a draft email that you can edit before sending.

Things happen; you might have to backfill a number of blog posts and you want to exclude them from your automation or you might want to pause your newsletter for a few weeks while you're tweaking the feed. Buttondown supports several ways to manage your RSS automation:

1. You can pause the automation, which will prevent any new emails from being sent or drafts from being created. Any items that are detected in your RSS feed will be ignored, and will not be automatically queued up for sending or drafting when you unpause the automation.
2. You can skip individual items in your RSS feed. This will prevent the automation from sending or drafting an email for that item, but will not prevent it from sending or drafting emails for any other items in the feed. This concept only applies if you've set up your automation on a weekly or monthly cadence.
3. You can enable the skip old items setting, which will automatically skip any items with a publish date older than one day from when they're discovered. This is particularly useful when first setting up an RSS feed that already has existing content—it ensures you only send truly new posts going forward, without accidentally sending outdated content to your subscribers.

(Of course, you can always just delete the automation and create a new one!)

RSS is a fairly open-ended spec, and there are a number of implementations that are all correct in different ways. Below is a list of the important fields that Buttondown tries to extract and how it extracts them, in order:

1. title: Buttondown looks for the title field in the RSS item. If it's not found, it looks for the dc:title field. If that's not found, it looks for the description field.
2. content: Buttondown looks for the content:encoded field in the RSS item. If it's not found, it looks for the summary_detail field.
3. url: Buttondown looks for the link field in the RSS item.
4. publish_date: Buttondown looks for the published field in the RSS item. If it's not found, it looks for the updated field.
5. description: Buttondown looks for the subtitle field in the RSS item. If it's not found, it looks for the summary field.

Here's a simple example of the minimum possible RSS entry that Buttondown needs in RSS 2.0:

<item>
    <title>
        <![CDATA[ 2023-01-16 ]]>
    </title>
    <link>https://buttondown.com/changelog/2023-01-16</link>
    <pubDate>Mon, 16 Jan 2023 00:00:00 GMT</pubDate>
    <description>
        Buttondown makes sure your images are accessible and SEO-friendly
    </description>
    <content:encoded>
        <![CDATA[
            <p>
            <img
              src="/next-assets/img/changelog/alt-text.png"
              alt="A screenshot of the modal that informs you to add ALT text"
            ></p>
            <p>
              Buttondown now has a friendly reminder to add alt text to your images
              before sending your email.
            </p>
            <p>
                Adding alt text (alternative text) to your images is a great
                way to make sure your emails are accessible to everyone,
                including people who use screen readers. It&#39;s also a great
                way to make sure your emails are SEO-friendly!
            </p>
        ]]>
    </content:encoded>
</item>

Here's a similar example, except in Atom 1.0:

<entry>
    <title>2023-01-16</title>
    <link href="https://buttondown.com/changelog/2023-01-16"/>
    <updated>2023-01-16T16:22:55Z</updated>
    <id>https://buttondown.com/changelog/2023-01-16</id>
    <content type="html">
        <p>
            <img
              src="/next-assets/img/changelog/alt-text.png"
              alt="A screenshot of the modal that informs you to add ALT text"
            >
        </p>
            <p>
              Buttondown now has a friendly reminder to add alt text to your images
              before sending your email.
            </p>
            <p>
                Adding alt text (alternative text) to your images is a great
                way to make sure your emails are accessible to everyone,
                including people who use screen readers. It&#39;s also a great
                way to make sure your emails are SEO-friendly!
            </p>
    </content>
</entry>

To populate your email with content relevant to the item in your RSS feed, you'll need to build a template. Buttondown uses Django's template language to render your email. This means that you can use all of the standard Django template tags and filters.

For instance, if you want to send a weekly digest of blog posts, you'd start by iterating over the list of items:

We published the following essays this week:

{% for item in items %}
    <h2>{{ item.title }}</h2>
    <p>{{ item.description }}</p>
    <p><a href="{{ item.url }}">Read more</a></p>
{% endfor %}

Or if you chose a cadence of "every time" for your RSS feed, you'd just send information on the latest item:

We're the first to admit that there's a lot of esoteric features and functionality when it comes to RSS. Here's a (assuredly incomplete) list of things that Buttondown either does or doesn't support:

• Buttondown supports the xml:base attribute, which allows you to specify a base URL for relative links in your RSS feed.
• Buttondown doesn't support base-64 encoded images in RSS feeds; those images won't be displayed in most email clients.

If Buttondown has trouble reaching your RSS feed (and you don't), the likely culprit is a firewall or proxy that's blocking access to the feed. In particular, Cloudflare's bot blocker is known to mistakenly block access to Buttondown's feed parser.

To fix this, add a custom WAF rule to your Cloudflare account to allow requests from the IP address 54.221.205.107.

It's also possible that you might have a robots.txt file that's blocking access to your feed. Buttondown uses the User-Agent: Buttondown RSS-Feed-Parser/1.0 (https://buttondown.com) user agent to access your feed, so you can add a Allow: line to your robots.txt file to allow Buttondown's feed parser to access your feed.

Items in an RSS feed my be marked as irrelevant for two reasons:

1. They do not have a publish date associated with them
2. The publish date came before the RSS feed itself was connected to Buttondown