Export

Some software applications may want programmatic access to their newsletter exports. This assists with a few niche use cases, such as regular backups or data ingestion (into a data warehouse), or post-publishing processes that hinge on email events.

In general, you probably won't need to use this endpoint unless you absolutely need to use this endpoint.

Basic export

{
"creation_date": "2019-08-24T14:15:22Z",
"completion_date": "2019-08-24T15:15:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"url": "s3://buttondown/path-to-export",
"status": "completed"
}
fieldtypedescription
idstring
creation_datestring
statusExportStatus
urlstring
completion_datestring

Collection (ExportCollection)

A group of data that can be exported in an export.


typeidentifierdescription
Subscribers
subscribers
Emails
emails
Scheduled emails
scheduled_emails
Drafts
drafts
Unsubscribers
unsubscribers
Events
events
Referrals
referrals

Status (ExportStatus)

Represents the status of an export. No action is required to move from one state or another; Buttondown internally handles the transitions, and exposing the status is for observability purposes only.


typeidentifierdescription
Not started
not_startedThe export has not yet started
In progress
in_progressThe export is currently being processed
ready
readyThe export has completed
error
errorThe export was unable to be completed. Buttondown is looking into it.

Create Export

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
"Authorization": f"Token {BUTTONDOWN_API_KEY}",
}
BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/exports"
response = requests.post(f"{BASE_URL}{ENDPOINT}", headers=headers)

Parameters

parametertypedescriptionoptional
collectionsarray

Responses

StatusDescriptionSample Response
201Created
{
"creation_date": "2019-08-24T14:15:22Z",
"completion_date": "2019-08-24T15:15:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"url": "s3://buttondown/path-to-export",
"status": "completed"
}
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
No collections passed in
collection_empty_invalidYou must pass in at least one collection to export

List Exports

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
"Authorization": f"Token {BUTTONDOWN_API_KEY}",
}
BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/exports"
response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)

Responses

StatusDescriptionSample Response
200OK
{
"results": [
{
"creation_date": "2019-08-24T14:15:22Z",
"completion_date": "2019-08-24T15:15:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"url": "s3://buttondown/path-to-export",
"status": "completed"
}
],
"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
{}

Retrieve Export

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
"Authorization": f"Token {BUTTONDOWN_API_KEY}",
}
BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/exports/{pk}"
response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)

Responses

StatusDescriptionSample Response
200OK
{
"creation_date": "2019-08-24T14:15:22Z",
"completion_date": "2019-08-24T15:15:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"url": "s3://buttondown/path-to-export",
"status": "completed"
}
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
{}