Log in or sign up for an account

Newsletter

You will likely not need to interact with your newsletter settings programmatically, but if you do, this is the endpoint for you. You can create, update, and list newsletters via the API; this is ideal for integrating with Buttondown as a headless email or newsletter provider (e.g. for a SaaS product.)

Basic newsletter

{
    "api_key": "7f819f8f-8220-4dcd-b7e3-37c81ead8b7a",
    "creation_date": "2019-08-24T14:15:22Z",
    "description": "I write about corgis and Python and lifting and all sorts of stuff!",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Justin's neat newsletter",
    "username": "jmduke",
    "footer": "Thanks, as always, for reading!",
    "header": "Howdy, gang!",
    "tint_color": "#0069FF",
    "from_name": "Justin Duke"
}
fieldtypedescription
idstring
usernamestring
namestring
descriptionstring
creation_datestring
api_keystring
tint_colorstring
from_namestring
headerstring
footerstring
domainstring
email_domainstring
enabled_featuresarray
custom_email_templatestring

List Newsletters

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/newsletters"


response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)

Responses

StatusDescriptionSample Response
200OK
{
    "results": [
        {
            "api_key": "7f819f8f-8220-4dcd-b7e3-37c81ead8b7a",
            "creation_date": "2019-08-24T14:15:22Z",
            "description": "I write about corgis and Python and lifting and all sorts of stuff!",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "name": "Justin's neat newsletter",
            "username": "jmduke",
            "footer": "Thanks, as always, for reading!",
            "header": "Howdy, gang!",
            "tint_color": "#0069FF",
            "from_name": "Justin Duke"
        }
    ],
    "count": 1
}
400Bad Request
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
409Conflict
{}

Create Newsletter

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/newsletters"


response = requests.post(f"{BASE_URL}{ENDPOINT}", headers=headers)

Parameters

parametertypedescriptionoptional
usernamestring
namestring
descriptionstring
tint_colorstring
from_namestring
headerstring
footerstring
domainstring
email_domainstring
enabled_featuresarray
custom_email_templatestring

Responses

StatusDescriptionSample Response
201Created
{
    "api_key": "7f819f8f-8220-4dcd-b7e3-37c81ead8b7a",
    "creation_date": "2019-08-24T14:15:22Z",
    "description": "I write about corgis and Python and lifting and all sorts of stuff!",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Justin's neat newsletter",
    "username": "jmduke",
    "footer": "Thanks, as always, for reading!",
    "header": "Howdy, gang!",
    "tint_color": "#0069FF",
    "from_name": "Justin Duke"
}
400Bad Request
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
409Conflict
{}

Error codes

typeidentifierdescription
Username invalid
username_invalidThe username is invalid.
Username already exists
username_already_existsA newsletter already exists with that username.

Update Newsletter

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/newsletters/{id}"


response = requests.patch(f"{BASE_URL}{ENDPOINT}", headers=headers)

Parameters

parametertypedescriptionoptional
usernamestring
namestring
descriptionstring
tint_colorstring
from_namestring
headerstring
footerstring
domainstring
email_domainstring
enabled_featuresarray
custom_email_templatestring

Responses

StatusDescriptionSample Response
200OK
{
    "api_key": "7f819f8f-8220-4dcd-b7e3-37c81ead8b7a",
    "creation_date": "2019-08-24T14:15:22Z",
    "description": "I write about corgis and Python and lifting and all sorts of stuff!",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Justin's neat newsletter",
    "username": "jmduke",
    "footer": "Thanks, as always, for reading!",
    "header": "Howdy, gang!",
    "tint_color": "#0069FF",
    "from_name": "Justin Duke"
}
400Bad Request
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
409Conflict
{}

Delete Newsletter

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/newsletters/{id}"


response = requests.delete(f"{BASE_URL}{ENDPOINT}", headers=headers)

Responses

StatusDescriptionSample Response
204No Content
{}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
404Not Found
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
409Conflict
{}