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

field	type	description
id	string
creation_date	string
status	ExportStatus
url	string
completion_date	string

Collection (ExportCollection)

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

type	identifier	description
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.

type	identifier	description
Not started	not_started	The export has not yet started
In progress	in_progress	The export is currently being processed
ready	ready	The export has completed
error	error	The 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

parameter	type	description	optional
collections	array

Responses

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

Status

Description

Sample Response

201

Created

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

403

Forbidden

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

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

Status	Description	Sample Response
200	OK	{ "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 }
400	Bad Request	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Status

Description

Sample Response

200

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

400

Bad Request

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

403

Forbidden

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

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

Status	Description	Sample Response
200	OK	{ "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" }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Status

Description

Sample Response

200

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

403

Forbidden

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

404

Not Found

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

On this page

Enums

Endpoints