Log in or sign up for an account

Scheduled emails

Scheduled emails are analogous to, well, scheduled emails; emails that you create to be sent at some point in the future. Depending on your integration, it might make more sense for you to create scheduled emails ahead of time rather than wait to create an email at exactly the time you want it going out (and, just like emails scheduled via Buttondown's UI, scheduled emails created via the API will automatically be sent out without requiring any further intervention.)

The scheduled email object

A scheduled 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": [],
    "publish_date": "2019-09-24T14:15:22Z",
    "email_type": "public"
}

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

Listing scheduled emails

GET → https://api.buttondown.email/v1/scheduled-emails

Parameters

parametertypedescriptionoptional
pagestring

A page number within the paginated result set. Each page has 100 results.

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": [],
            "publish_date": "2019-09-24T14:15:22Z",
            "email_type": "public"
        }
    ]
}

Scheduling a new email to be sent

POST → https://api.buttondown.email/v1/scheduled-emails

Parameters

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

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": [],
    "publish_date": "2019-09-24T14:15:22Z",
    "email_type": "public"
}

Retrieving a specific scheduled email

GET → https://api.buttondown.email/v1/scheduled-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": [],
    "publish_date": "2019-09-24T14:15:22Z",
    "email_type": "public"
}

Deleting a specific scheduled email

DELETE → https://api.buttondown.email/v1/scheduled-emails/<id>

Responses

StatusDescriptionSample Response
204
{}

Updating or rescheduling a specific scheduled email

PATCH → https://api.buttondown.email/v1/scheduled-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": [],
    "publish_date": "2019-09-24T14:15:22Z",
    "email_type": "public"
}