Email

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
is_comments_disabled	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.
Managed by RSS	managed_by_rss	This email was created by an external feed, and has not yet been finalized and sent out by Buttondown.
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

curl

python

ruby

typescript

Copy to clipboard

import requests
headers = {
    "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
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
is_comments_disabled	boolean
custom_teaser	string
secondary_id	integer
filters	array

Responses

Status	Description	Sample Response
201	Created	{ "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" }
400	Bad Request	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
409	Conflict	{}

Error codes

type	identifier	description
Invalid subject	subject_invalid
Invalid tag	tag_invalid
Duplicate email	email_duplicate
Invalid email	email_invalid

List Emails

curl

python

ruby

typescript

Copy to clipboard

import requests
headers = {
    "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
status	array	Note that for historical reasons, if `status` is not included in the query, the default is to only return emails with a status of `about_to_send`, `in_flight`, or `sent`. This is a legacy behavior and may change in the future. If you want to include drafts, you must explicitly include `draft` in the `status` query parameter. (Same thing with imported emails.)
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	{ "results": [ { "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" } ], "count": 1 }
400	Bad Request	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{}
409	Conflict	{}

Error codes

type	identifier	description

Update Email

curl

python

ruby

typescript

Copy to clipboard

import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}

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

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

Parameters

parameter	type	description
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
is_comments_disabled	boolean
custom_teaser	string
slug	string
secondary_id	integer
filters	array

Responses

Status	Description	Sample Response
200	OK	{ "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" }
400	Bad Request	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
409	Conflict	{}

Retrieve Email

curl

python

ruby

typescript

Copy to clipboard

import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}

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

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

Responses

Status	Description	Sample Response
200	OK	{ "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" }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
409	Conflict	{}

Retrieve Email Analytics

curl

python

ruby

typescript

Copy to clipboard

import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}

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

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

Responses

Status	Description	Sample Response
200	OK	{ "recipients": 100, "deliveries": 99, "opens": 50, "clicks": 25, "temporary_failures": 1, "permanent_failures": 2, "unsubscriptions": 3, "complaints": 1 }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
409	Conflict	{}

Send Draft

curl

python

ruby

typescript

Copy to clipboard

import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}

BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/emails/{id}/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	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
409	Conflict	{}

On this page

Enums

Endpoints

/emails/{id}/analytics

/emails/{id}/send-draft