Scheduling emails via the API

We've already covered how to create, list, and update emails using the Buttondown API. Here, we’ll take things a step further by learning how to programmatically schedule emails. This may come in handy if:

• You like to plan ahead.
• You want to send your email at a time when your subscribers are most likely to read and engage with it.
• The content of your email is timed to a specific holiday, event, or other notable date.

The best part? We only have to add two new lines of code.

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

import json

import requests

# You can find this key in your API requests page:
# https://buttondown.com/requests
BUTTONDOWN_API_KEY = "your-api-key-here"

headers = {"Authorization": f"Token #{BUTTONDOWN_API_KEY}"}
base_url = "https://api.buttondown.email"
endpoint = "/v1/emails"
data = {
    "subject": "Scheduled for the future",
    "body": "Welcome to my time-traveling email!",
    "status": "scheduled",
    "publish_date": "2027-08-24T14:15:22Z",
}
response = requests.post(
    base_url + endpoint, headers=headers, data=json.dumps(data)
).json()
print(response)

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 json

import requests

# You can find this key in your API requests page:
# https://buttondown.com/requests
BUTTONDOWN_API_KEY = "your-api-key-here"

headers = {"Authorization": f"Token #{BUTTONDOWN_API_KEY}"}
data = {
    "publish_date": "#{NEW_PUBLISH_DATE}",
}
base_url = "https://api.buttondown.email"
endpoint = "/v1/emails/#{EMAIL_ID}"
response = requests.patch(base_url + endpoint, headers=headers, data=json.dumps(data))
print(response)

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 json

import requests

# You can find this key in your API requests page:
# https://buttondown.com/requests
BUTTONDOWN_API_KEY = "your-api-key-here"

headers = {"Authorization": f"Token #{BUTTONDOWN_API_KEY}"}
data = {
    "status": "draft",
}
base_url = "https://api.buttondown.email"
endpoint = "/v1/emails/#{EMAIL_ID}"
response = requests.patch(base_url + endpoint, headers=headers, data=json.dumps(data))
print(response)