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","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 | string | |
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 |
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 | |
About to send | about_to_send | |
Scheduled | scheduled | |
In flight | in_flight | |
Imported | imported | |
Deleted | deleted | |
Sent | sent | |
Errored | errored |
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
$ curl -X POST https://api.buttondown.email/v1/emails
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 |
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
$ curl -X GET https://api.buttondown.email/v1/emails
Parameters
parameter | type | description | optional |
---|---|---|---|
status | array | ||
included_tags | array | ||
excluded_tags | array | ||
automations | array | ||
ids | array | ||
ordering | unknown |
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
400 | Bad Request |
|
403 | Forbidden |
|
404 | Not Found |
|
Update Email
$ curl -X PATCH https://api.buttondown.email/v1/emails/{pk}
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 |
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
400 | Bad Request |
|
403 | Forbidden |
|
404 | Not Found |
|
Retrieve Email
$ curl -X GET https://api.buttondown.email/v1/emails/{pk}
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
403 | Forbidden |
|
404 | Not Found |
|
Retrieve Email Analytics
$ curl -X GET https://api.buttondown.email/v1/emails/{pk}/analytics
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
403 | Forbidden |
|
Send Draft
$ curl -X POST https://api.buttondown.email/v1/emails/{pk}/send-draft
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 |
|