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 -X POST https://api.buttondown.email/v1/exports

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"
}
403Forbidden
{
"code": "something_went_wrong",
"detail": "Your call is very important to us."
}

List Exports

$ curl -X GET https://api.buttondown.email/v1/exports

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."
}

Retrieve Export

$ curl -X GET https://api.buttondown.email/v1/exports/{pk}

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."
}