Emails

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.

The email object

An email looks like this:

{
"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",
"metadata": {},
"secondary_id": 3,
"external_url": "https://buttondown.email/jmduke/my-first-email"
}

fieldtypedescription
iduuid
creation_datedatetime
publish_datedatetime
subjectstring
email_typeEmailType
bodystring
included_tagsarray<string> | array<uuid>
excluded_tagsarray<string> | array<uuid>
metadatamap

Email types

Email types govern the visibility of an email, both in the sense of to whom it is originally delivered and whom can view it after it's been sent out. By default, all emails are public.

typedescription
publicPublic emails are sent out to all of your subscribers and are available in your web archives.
privatePrivate emails are sent out to all of your subscribers but are not viewable in your web archives.
premiumPremium 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.
freeFree 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!)

Listing emails

GET https://api.buttondown.email/v1/emails

Parameters

parametertypedescriptionoptional
pagestringA page number within the paginated result set.

Responses

StatusDescriptionSample Response
200
{
"count": 1,
"next": "foo",
"previous": null,
"results": [
{
"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",
"metadata": {},
"secondary_id": 3,
"external_url": "https://buttondown.email/jmduke/my-first-email"
}
]
}

Sending an email

POST https://api.buttondown.email/v1/emails

Parameters

parametertypedescriptionoptional
bodystring
subjectstring
email_typestring
excluded_tagsarray<string> | array<uuid>
included_tagsarray<string> | array<uuid>
metadatamap

Responses

StatusDescriptionSample Response
201
{
"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",
"metadata": {},
"secondary_id": 3,
"external_url": "https://buttondown.email/jmduke/my-first-email"
}

Retrieving a specific email

GET https://api.buttondown.email/v1/emails/<id>

Responses

StatusDescriptionSample Response
200
{
"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",
"metadata": {},
"secondary_id": 3,
"external_url": "https://buttondown.email/jmduke/my-first-email"
}