Log in or sign up for an account

ExternalFeed

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

Basic automation

{
    "creation_date": "2019-08-24T14:15:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "active",
    "behavior": "emails",
    "cadence": "every",
    "subject": "New post: {{ item.title }}",
    "body": "I just published a new post: {{ item.url }}"
}
fieldtypedescription
idstring
creation_datestring
last_checked_datestring
statusExternalFeedAutomationStatus
behaviorExternalFeedAutomationBehavior
cadenceExternalFeedAutomationCadence
cadence_metadataobject
included_tagsarray
urlstring
subjectstring
bodystring
labelstring

Behavior (ExternalFeedAutomationBehavior)

An enumeration.


typeidentifierdescription
Create draft
draftCreate a draft email.
Send email
emailsSend emails to subscribers.

Status (ExternalFeedAutomationStatus)

An enumeration.


typeidentifierdescription
Active
activeActive.
Inactive
inactiveInactive.

Cadence (ExternalFeedAutomationCadence)

An enumeration.


typeidentifierdescription
Every new item
everyAct every single time a new item is added to the RSS feed.
Weekly
weeklyAct every week, compiling a digest of new items.
Monthly
monthlyAct every month, compiling a digest of new items.

Create External Feed

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/external_feeds"


response = requests.post(f"{BASE_URL}{ENDPOINT}", headers=headers)

Parameters

parametertypedescriptionoptional
urlstring
behavior
cadence
cadence_metadataobject
included_tagsarray
subjectstring
bodystring
labelstring

Responses

StatusDescriptionSample Response
201Created
{
    "creation_date": "2019-08-24T14:15:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "active",
    "behavior": "emails",
    "cadence": "every",
    "subject": "New post: {{ item.title }}",
    "body": "I just published a new post: {{ item.url }}"
}
400Bad Request
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
409Conflict
{}

List External Feed

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/external_feeds"


response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)

Responses

StatusDescriptionSample Response
200OK
{
    "results": [
        {
            "creation_date": "2019-08-24T14:15:22Z",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "status": "active",
            "behavior": "emails",
            "cadence": "every",
            "subject": "New post: {{ item.title }}",
            "body": "I just published a new post: {{ item.url }}"
        }
    ],
    "count": 1
}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
409Conflict
{}

Update External Feed

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/external_feeds/{id}"


response = requests.patch(f"{BASE_URL}{ENDPOINT}", headers=headers)

Parameters

parametertypedescriptionoptional
behavior
cadence
cadence_metadataobject
included_tagsarray
subjectstring
bodystring
labelstring
status

Responses

StatusDescriptionSample Response
200OK
{
    "creation_date": "2019-08-24T14:15:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "active",
    "behavior": "emails",
    "cadence": "every",
    "subject": "New post: {{ item.title }}",
    "body": "I just published a new post: {{ item.url }}"
}
400Bad Request
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
409Conflict
{}

Delete External Feed

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/external_feeds/{id}"


response = requests.delete(f"{BASE_URL}{ENDPOINT}", headers=headers)

Responses

StatusDescriptionSample Response
204No Content
{}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
404Not Found
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
409Conflict
{}

Retrieve External Feed

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/external_feeds/{id}"


response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)

Responses

StatusDescriptionSample Response
200OK
{
    "creation_date": "2019-08-24T14:15:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "active",
    "behavior": "emails",
    "cadence": "every",
    "subject": "New post: {{ item.title }}",
    "body": "I just published a new post: {{ item.url }}"
}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
404Not Found
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
409Conflict
{}