Drafting emails via the API

Got a great idea for an email, and want to jot it down quickly? Buttondown’s API makes it possible to create a draft at the drop of a hat.

One thing before we get going: It’s always a good idea to have our API reference doc on hand in case you need it!

Ready to put pen to paper? All you’ll need is a catchy subject line, a fun idea for your body text, and a few lines of code.

import requests

url = "https://api.buttondown.com/v1/emails"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "subject": "My first draft",
  "body": "Hello, world!",
  "status": "draft"
}

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

Drafts follow a similar set of parameters as regular emails, with just one exception: The “Status” must be set as “Draft.”

You’ve jotted down your draft—but how do you know if your API request was successful? Here are three ways to check:

• Visit the API reference tab of your Buttondown dashboard.
• Compare your response to the ones listed in our API reference doc.
• Take a look at the “Emails” tab of your Buttondown dashboard. You should see your email “Status” listed as a “Draft.”

Want to see how your draft is shaping up? You can conjure it with an email ID, along with a few new lines of code.

Before we get to the code, here are two ways to find your email ID:

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

Now you're ready to use the following code.

import requests

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

response = requests.request("GET", url, headers=headers)
print(response.text)

If the editing mood strikes, you can always update the body of your draft using the code below.

import requests

url = "https://api.buttondown.com/v1/emails/{id}"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "body": "Hello, updated world!"
}

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

Congratulations, your draft is ready to become a fully-fledged email! Go ahead and send it out with just a few more adjustments to your code.

The main change will be to your draft’s “Status.” We’ll switch it from “Draft” to “About to Send.” Once you submit your request, Buttondown will automatically begin the process of sending your email.

(Pro tip: If you spot a typo and want to undo sending your email, you’ll still have a few minutes to do so! All you need to do is change the “Status” back to “Draft.”)

import requests

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

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

If you’d rather wait a bit to send your draft, you can simply change your draft “Status” to “Scheduled” instead. You’ll also need to add a “Publish date” in the following format: “YYYY-MM-DDTHH:MM:SSZ.”

import requests

url = "https://api.buttondown.com/v1/emails/{id}"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "status": "scheduled",
  "publish_date": "2024-12-31T12:00:00Z"
}

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