Emails are what you're for here on Buttondown at the end of the day, right? Creating an email via the API is just like creating one in the interface; it will instantly trigger sending actual emails, based on the tags and email type you provide.
Basic email
{"creation_date": "2019-08-24T14:15:22Z","publish_date": "2024-08-24T14:15:22Z","id": "497f6eca-6276-4993-bfeb-53cbbbba6f08","body": "Lorem ipsum yadda yadda","subject": "This is my first email on Buttondown!","excluded_tags": [],"included_tags": [],"email_type": "public","status": "sent","metadata": {},"secondary_id": 3,"external_url": "https://buttondown.email/jmduke/my-first-email"}
Basic draft
{"creation_date": "2019-08-24T14:15:22Z","id": "497f6eca-6276-4993-bfeb-53cbbbba6f08","body": "Lorem ipsum yadda yadda","subject": "This is my first email on Buttondown!","excluded_tags": [],"included_tags": [],"status": "draft","email_type": "public","metadata": {},"secondary_id": 3,"external_url": "https://buttondown.email/jmduke/my-first-email"}
Basic scheduled email
{"creation_date": "2019-08-24T14:15:22Z","publish_date": "2024-08-24T14:15:22Z","id": "497f6eca-6276-4993-bfeb-53cbbbba6f08","body": "Lorem ipsum yadda yadda","subject": "This is my first email on Buttondown!","excluded_tags": [],"included_tags": [],"status": "scheduled","email_type": "public","metadata": {},"secondary_id": 3,"external_url": "https://buttondown.email/jmduke/my-first-email"}
field | type | description |
---|---|---|
id | string | |
included_tags | array | |
excluded_tags | array | |
creation_date | string | |
modification_date | string | |
publish_date | string | |
attachments | array | |
subject | string | |
canonical_url | string | |
image | string | |
description | string | |
source | EmailSource | |
body | string | Can be either HTML or markdown. |
secondary_id | integer | |
email_type | EmailType | |
slug | string | |
external_url | string | |
status | EmailStatus | |
metadata | object | |
should_send_teaser | boolean | |
custom_teaser | string | |
absolute_url | string | |
filters | array | |
analytics | Analytics |
Status (EmailStatus)
Represents the state of an email. No action is required to move from one state or another; Buttondown internally handles the transitions, and exposing the status is for observability purposes only.
type | identifier | description |
---|---|---|
Draft | draft | Draft emails are only visible to you and are not sent out to subscribers. |
About to send | about_to_send | This email has been queued to send out to subscribers, and will be sent automatically within a few minutes. |
Scheduled | scheduled | This email has been scheduled to send out to subscribers at a specific time (stored in `publish_date`). |
In flight | in_flight | This email is currently being sent out to subscribers, and is visible in your web archives if enabled. |
Imported | imported | This email was imported from another service, and is visible in your web archives if enabled. |
Deleted | deleted | This email has been deleted, and is no longer visible in your web archives. |
Paused | paused | This email has been paused, and is not visible in your web archives. |
Sent | sent | This email has been sent out to subscribers, and is visible in your web archives if enabled. |
Errored | errored | This email has encountered an error while sending out to subscribers, and is not visible in your web archives. |
Type (EmailType)
Represents the audience of an email, and to whom it is visible both in the initial email and in online archives.
type | identifier | description |
---|---|---|
Public | public | Public emails are sent out to all of your subscribers and are available in your web archives. |
Private | private | Private emails are sent out to all of your subscribers but are not viewable in your web archives. |
Premium | premium | Premium emails are sent out to only paying subscribers (including those with gift subscriptions or on a free trial), and only premium subscribers can view them in online archives. |
Free | free | Free emails are sent out only to subscribers who are not paying for your newsletter (so you can send specific emails to convince them to pay, for instance!) |
Create Email
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/emails"response = requests.post(f"{BASE_URL}{ENDPOINT}", headers=headers)
Parameters
parameter | type | description | optional |
---|---|---|---|
included_tags | array | ||
excluded_tags | array | ||
attachments | array | ||
publish_date | string | ||
subject | string | ||
slug | string | ||
description | string | ||
canonical_url | string | ||
image | string | ||
body | string | Can be either HTML or markdown. | |
email_type | |||
status | |||
metadata | object | ||
should_send_teaser | boolean | ||
custom_teaser | string | ||
filters | array |
Responses
Status | Description | Sample Response |
---|---|---|
201 | Created |
|
400 | Bad Request |
|
403 | Forbidden |
|
Error codes
type | identifier | description |
---|---|---|
Invalid subject | subject_invalid | |
Duplicate email | email_duplicate | |
Invalid email | email_invalid |
List Emails
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/emails"response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)
Parameters
parameter | type | description | optional |
---|---|---|---|
status | array | ||
included_tags | array | ||
excluded_tags | array | ||
automations | array | ||
ids | array | ||
ordering | unknown | ||
creation_date__start | string | ||
creation_date__end | string | ||
publish_date__start | string | ||
publish_date__end | string | ||
excluded_fields | array | ||
source | array | ||
email_type | array |
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
400 | Bad Request |
|
403 | Forbidden |
|
404 | Not Found |
|
Update Email
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/emails/{pk}"response = requests.patch(f"{BASE_URL}{ENDPOINT}", headers=headers)
Parameters
parameter | type | description | optional |
---|---|---|---|
included_tags | array | ||
excluded_tags | array | ||
attachments | array | ||
publish_date | string | ||
subject | string | ||
description | string | ||
canonical_url | string | ||
body | string | Can be either HTML or markdown. | |
email_type | |||
status | |||
metadata | object | ||
image | string | ||
should_send_teaser | boolean | ||
custom_teaser | string | ||
slug | string | ||
secondary_id | integer | ||
filters | array |
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
400 | Bad Request |
|
403 | Forbidden |
|
404 | Not Found |
|
Retrieve Email
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/emails/{pk}"response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
403 | Forbidden |
|
404 | Not Found |
|
Retrieve Email Analytics
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/emails/{pk}/analytics"response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
403 | Forbidden |
|
404 | Not Found |
|
Send Draft
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/emails/{pk}/send-draft"response = requests.post(f"{BASE_URL}{ENDPOINT}", headers=headers)
Parameters
parameter | type | description | optional |
---|---|---|---|
subscribers | array | A list of subscriber ids to which to send the email. | |
recipients | array | A list of email addresses to send the email to. |
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
400 | Bad Request |
|
403 | Forbidden |
|
404 | Not Found |
|