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"}
field | type | description |
---|---|---|
id | string | |
username | string | |
name | string | |
description | string | |
creation_date | string | |
api_key | string | |
tint_color | string | |
from_name | string | |
header | string | |
footer | string | |
domain | string | |
email_domain | string | |
enabled_features | array | |
custom_email_template | string |
List Newsletters
curl
python
ruby
typescript
Copy to clipboard
import requestsheaders = {"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
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
400 | Bad Request |
|
403 | Forbidden |
|
Create Newsletter
curl
python
ruby
typescript
Copy to clipboard
import requestsheaders = {"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
parameter | type | description | optional |
---|---|---|---|
username | string | ||
name | string | ||
description | string | ||
tint_color | string | ||
from_name | string | ||
header | string | ||
footer | string | ||
domain | string | ||
email_domain | string | ||
enabled_features | array | ||
custom_email_template | string |
Responses
Status | Description | Sample Response |
---|---|---|
201 | Created |
|
400 | Bad Request |
|
403 | Forbidden |
|
Error codes
type | identifier | description |
---|---|---|
Username already exists | username_already_exists | A newsletter already exists with that username |
Update Newsletter
curl
python
ruby
typescript
Copy to clipboard
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/newsletters/{pk}"response = requests.patch(f"{BASE_URL}{ENDPOINT}", headers=headers)
Parameters
parameter | type | description | optional |
---|---|---|---|
username | string | ||
name | string | ||
description | string | ||
tint_color | string | ||
from_name | string | ||
header | string | ||
footer | string | ||
domain | string | ||
email_domain | string | ||
enabled_features | array | ||
custom_email_template | string |
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
400 | Bad Request |
|
403 | Forbidden |
|
Delete Newsletter
curl
python
ruby
typescript
Copy to clipboard
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/newsletters/{pk}"response = requests.delete(f"{BASE_URL}{ENDPOINT}", headers=headers)
Responses
Status | Description | Sample Response |
---|---|---|
204 | No Content |
|
403 | Forbidden |
|
404 | Not Found |
|