Scheduling emails via the API

It only takes two extra lines of code to specify your email’s “Status” and “Publish Date.”

import requests

url = "https://api.buttondown.com/v1/emails"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "subject": "My scheduled email",
  "body": "Hello, future!",
  "status": "scheduled",
  "publish_date": "2024-12-31T12:00:00Z"
}

response = requests.request("POST", url, headers=headers, json=data)
print(response.text)

Scheduled emails follow a similar set of parameters as non-scheduled emails —that is, except for the “Publish Date” and “Status.” In this case, “Publish Date” should be a date and time in the future, and “Status” should be “Scheduled.”

So you’ve submitted your request to the Buttondown API. How do you know if it worked? There are three ways to check:

• Visit the API reference tab in your Buttondown dashboard.
• Compare your response to the ones listed in our “Emails” API reference doc.
• Take a look at the “Emails” tab of your Buttondown dashboard. If your request was successful, you’ll see your email subject, along with a status of “Scheduled”!

Change your mind about your email's pub date? No worries—it’s a quick fix. All you need is an "Email ID" and a few more lines of code.

How do you find your “Email ID” you may ask? There are two ways:

• Pinpoint your “Email ID” in the response of your last successful request for that particular email.
• Mosey over to the “Emails” tab of your Buttondown dashboard, and click on the email in question. From there, you can copy the “Email ID” from the email’s URL.

Once you have your "Email ID" at the ready, you can use the following code to update your "Publish Date."

import requests

url = "https://api.buttondown.com/v1/emails/{id}"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "publish_date": "2025-01-01T12:00:00Z"
}

response = requests.request("PATCH", url, headers=headers, json=data)
print(response.text)

Stuff happens. If you decide that you’d rather save your scheduled email as a draft for later, you can do so by changing your email’s "Status."

import requests

url = "https://api.buttondown.com/v1/emails/{id}"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "status": "draft"
}

response = requests.request("PATCH", url, headers=headers, json=data)
print(response.text)