Buttondown logo

Introduction

Statuses

flowchart
    rss([example.com/rss.xml]) --> inactive[Inactive]
    inactive e1@--> active[Active]
    active e2@--> inactive
    active e3@--> |If Buttondown can't access the feed| failing[Failing]
    failing e4@--> |After three attempts| inactive
    e3@{ animate: true }
    e4@{ animate: true }

Item statuses

flowchart
    subgraph example.com/rss.xml
      1([example.com/post/1])
      2([example.com/post/2])
      3([example.com/post/3])
    end
    3 e1@--> not_started[Not started]
    not_started e2@--> |If published before the feed was added| irrelevant[Irrelevant]
    not_started e3@--> |If feed is inactive| skipped[Skipped]
    not_started e4@--> queued[Queued]
    queued e5@--> processed[Processed]
    queued e6@--> errored[Errored]
    processed e7@--> Email>email.created]
    e1@{ animate: true }
    e2@{ animate: true }
    e3@{ animate: true }
    e4@{ animate: true }
    e5@{ animate: true }
    e6@{ animate: true }
    e7@{ animate: true }
values
  • unprocessed

    Unprocessed.

  • irrelevant

    Items in an RSS feed are marked as irrelevant if they do not have a publish date associated with them or if the publish date came before the RSS feed itself was connected to Buttondown.

  • errored

    Errored.

  • skipped

    Items in an RSS feed are marked as 'skipped' if the RSS feed itself is paused or inactive in Buttondown when the item is processed. To send this item, you must manually process & send it using Buttondown's writing interface.

  • queued

    Items in an RSS feed are marked as queued once Buttondown has discovered them and determined they should be turned into an email. Queued items will be converted into an email on the next scheduled run for the feed's cadence.

  • processed

    Items in an RSS feed are marked as processed once Buttondown has created an email for them. Depending on the feed's behavior, the email is either saved as a draft for the author to edit or scheduled to send automatically.

An automation is a one-to-one mapping between an external RSS feed and an action to be performed when new items are detected in that feed. Right now, Buttondown offers two actions:

  • Send an email
  • Create an email but save it as a draft to be sent out manually

The automation is configured with a cadence, which is the frequency at which the automation will be run. The cadence can be one of the following:

  • Run the automation every time a new item is detected in the feed
  • Run the automation once per week
  • Run the automation once per month
{
    "id": "rss_0k28edc3fw896bp4mrhc535z5k",
    "creation_date": "2020-09-29T00:00:00+00:00",
    "last_checked_date": null,
    "status": "active",
    "behavior": "draft",
    "cadence": "daily",
    "cadence_metadata": {},
    "filters": {
        "filters": [],
        "groups": [],
        "predicate": "and"
    },
    "url": "https://example.com/feed",
    "subject": "New post: {{ item.title }}",
    "body": "I just published a new post: {{ item.url }}",
    "label": "Basic external feed",
    "metadata": {},
    "skip_old_items": true
}

Fields

idstring

A unique TypeID associated with the object.

creation_datestring

The date and time at which the object was first created.

last_checked_datestring

The most recent date and time this feed was checked for new items.

statusstring · enum

The current status of the external feed automation.

values
  • active

    Active.

  • failing

    Buttondown cannot retrieve items from this feed. It will continue to attempt to do so until it gives up, at which point the automation will be set to inactive.

  • inactive

    Inactive.

  • deleted

    The automation has been deleted.

behaviorstring · enum

Whether feed items are sent immediately or drafted for manual review.

values
  • draft

    Create a draft email.

  • emails

    Send emails to subscribers.

cadencestring · enum

How frequently this feed should create or draft emails.

values
  • every

    Act every single time a new item is added to the RSS feed.

  • daily

    Act every day, compiling a digest of new items.

  • weekly

    Act every week, compiling a digest of new items.

  • monthly

    Act every month, compiling a digest of new items.

cadence_metadataobject

Additional scheduling details for the selected cadence. time is required for daily/weekly/monthly cadences; weekday is required for weekly; monthday is required for monthly. See the cadence metadata reference for allowed values.

filtersFilterGroup

Tag-based filtering rules used to decide which subscribers receive feed-generated emails.

urlstring

The URL of the RSS feed to poll for new items.

subjectstring

The subject line template for emails generated from this feed.

bodystring

The body template for emails generated from this feed.

labelstring

An optional internal label for this feed.

metadataobject

Metadata to be passed to emails rendered by this RSS feed.

skip_old_itemsboolean

Skip items with publish date older than one day from when they're discovered