Buttondown Documentation

Buttondown Documentation

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook

Drafting emails via the API

info
This feature requires a Free plan.

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!

Starting your draft

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 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": "My fantastic draft idea!",
    "body": "Here's my amazing email draft!",
    "status": "draft",
}
response = requests.post(
    base_url + endpoint, headers=headers, data=json.dumps(data)
).json()
print(response)

Parameters

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

Results

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

Retrieving your 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

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

EMAIL_ID = "your-email-id-here"

headers = {"Authorization": f"Token #{BUTTONDOWN_API_KEY}"}
BASE_URL = "https://api.buttondown.email"
ENDPOINT = f"/v1/emails/{EMAIL_ID}"
response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)
print(response.json())

Editing your draft

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

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"
EMAIL_ID = "your-email-id-here"

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

Sending your draft

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 json

import requests

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

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

Scheduling your draft

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 json

import requests

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

headers = {"Authorization": f"Token #{BUTTONDOWN_API_KEY}"}
data = {
    "status": "scheduled",
    "publish_date": "2027-08-24T14:15:22Z",
}
base_url = "https://api.buttondown.email"
endpoint = f"/v1/emails/{EMAIL_ID}"
response = requests.patch(base_url + endpoint, headers=headers, data=json.dumps(data))
print(response)

Reach out to your friends at Buttondown

Our support team is always here to help. Just send us a message and we'll take a look!

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook