Log in or sign up for an account

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",
    "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"
}
fieldtypedescription
idstring
included_tagsarray
excluded_tagsarray
creation_datestring
modification_datestring
publish_datestring
attachmentsarray
subjectstring
canonical_urlstring
imagestring
descriptionstring
sourcestring
bodystringCan be either HTML or markdown.
secondary_idinteger
email_typeEmailType
slugstring
external_urlstring
statusEmailStatus
metadataobject
should_send_teaserboolean
custom_teaserstring
absolute_urlstring

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.


typeidentifierdescription
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.


typeidentifierdescription
Public
publicPublic emails are sent out to all of your subscribers and are available in your web archives.
Private
privatePrivate emails are sent out to all of your subscribers but are not viewable in your web archives.
Premium
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.
Free
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!)

Create Email

$ curl -X POST https://api.buttondown.email/v1/emails

Parameters

parametertypedescriptionoptional
included_tagsarray
excluded_tagsarray
attachmentsarray
publish_datestring
subjectstring
slugstring
descriptionstring
canonical_urlstring
imagestring
bodystring

Can be either HTML or markdown.

email_type
status
metadataobject
should_send_teaserboolean
custom_teaserstring

Responses

StatusDescriptionSample Response
201Created
{
    "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"
}
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."
}

Error codes

typeidentifierdescription
Invalid subject
subject_invalid
Duplicate email
email_duplicate
Invalid email
email_invalid

List Emails

$ curl -X GET https://api.buttondown.email/v1/emails

Parameters

parametertypedescriptionoptional
statusarray
included_tagsarray
excluded_tagsarray
automationsarray
idsarray
orderingunknown

Responses

StatusDescriptionSample Response
200OK
{
    "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",
            "status": "sent",
            "metadata": {},
            "secondary_id": 3,
            "external_url": "https://buttondown.email/jmduke/my-first-email"
        }
    ],
    "count": 1
}
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."
}
404Not Found
{}

Update Email

$ curl -X PATCH https://api.buttondown.email/v1/emails/{pk}

Parameters

parametertypedescriptionoptional
included_tagsarray
excluded_tagsarray
attachmentsarray
publish_datestring
subjectstring
descriptionstring
canonical_urlstring
bodystring

Can be either HTML or markdown.

email_type
status
metadataobject
imagestring
should_send_teaserboolean
custom_teaserstring
slugstring
secondary_idinteger

Responses

StatusDescriptionSample Response
200OK
{
    "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"
}
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."
}
404Not Found
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

Retrieve Email

$ curl -X GET https://api.buttondown.email/v1/emails/{pk}

Responses

StatusDescriptionSample Response
200OK
{
    "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"
}
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."
}

Retrieve Email Analytics

$ curl -X GET https://api.buttondown.email/v1/emails/{pk}/analytics

Responses

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

Send Draft

$ curl -X POST https://api.buttondown.email/v1/emails/{pk}/send-draft

Parameters

parametertypedescriptionoptional
subscribersarray

A list of subscriber ids to which to send the email.

recipientsarray

A list of email addresses to send the email to.

Responses

StatusDescriptionSample Response
200OK
{}
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."
}
404Not Found
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}