Buttondown logo

IntroductionStatusesSourcesAudiencesAnalyticsTemplatesCommenting modesSuppression reason

Audience filters

IntroductionFilteringOperators

Routes

Creating an emailListing emailsRetrieving emailUpdating an emailDeleting an emailRetrieving email analyticsSending a draft emailListing email eventsRetrieving email historyRetrieving an email's historical body

Buttondown logo

Listing emails

Sample requests

These sample requests are autogenerated by the OpenAPI spec.

import requests

url = "https://api.buttondown.com/v1/emails"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}

response = requests.request("GET", url, headers=headers)
print(response.text)

Sample responses

The IDs and values referenced in these responses are fake; please only rely on these responses for overall structure.

{
    "results": [
        {
            "absolute_url": "http://127.0.0.1:8000/sheinhardt/archive/welcome-to-the-newsletter/",
            "analytics": null,
            "attachments": [],
            "body": "I hope you really enjoy it!",
            "canonical_url": "",
            "commenting_mode": "enabled",
            "creation_date": "2000-01-01T00:00:00+00:00",
            "description": "",
            "email_type": "public",
            "featured": false,
            "filters": {
                "filters": [],
                "groups": [],
                "predicate": "and"
            },
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "image": "",
            "metadata": {},
            "modification_date": "2000-01-01T00:00:00+00:00",
            "publish_date": "2000-01-01T00:00:00+00:00",
            "related_email_ids": [],
            "secondary_id": null,
            "should_trigger_pay_per_email_billing": false,
            "slug": "welcome-to-the-newsletter",
            "source": "app",
            "status": "sent",
            "subject": "Welcome to the newsletter",
            "suppression_reason": null,
            "template": null
        }
    ],
    "count": 1
}

Path parameters

Consult the Filtering documentation for more information on how to filter and sort your requests.

status

Type
EmailStatus[]
Description

If provided, only return emails with the given status.

negative_status

Type
EmailStatus[]
Description

If provided, only return emails without the given status.

ids

Type
array
Description

If provided, only return emails with the given ids.

ordering

Type
string
Values
  • creation_date
  • -creation_date
  • status
  • -status
  • publish_date
  • -publish_date
  • subject
  • -subject
  • email_type
  • -email_type
  • modification_date
  • -modification_date
  • clicks
  • -clicks
  • opens
  • -opens
  • click_rate
  • -click_rate
  • open_rate
  • -open_rate
  • page_views_lifetime
  • -page_views_lifetime
  • page_views_30
  • -page_views_30
  • page_views_7
  • -page_views_7
  • webmentions
  • -webmentions
  • subscriptions
  • -subscriptions
  • paid_subscriptions
  • -paid_subscriptions
  • unsubscriptions
  • -unsubscriptions
  • replies
  • -replies
  • comments
  • -comments
  • social_mentions
  • -social_mentions
  • permanent_failure_rate
  • -permanent_failure_rate
  • complaint_rate
  • -complaint_rate

creation_date__start

Type
string
Description

If provided, only return emails created after the given date.

creation_date__end

Type
string
Description

If provided, only return emails created before the given date.

publish_date__start

Type
string
Description

If provided, only return emails published after the given date.

publish_date__end

Type
string
Description

If provided, only return emails published before the given date.

excluded_fields

Type
[]

source

Type
EmailSource[]

email_type

Type
EmailType[]
Description

The type of emails to return. Defaults to all types.

subject

Type
string
Description

If provided, only return emails with a subject that contains the given string.

attachments

Type
array
Description

If provided, only return emails with the given attachments.

Error codes

This endpoint may return the following error codes. See the error codes reference for more details about error handling.

Error CodeDescription
creation_date_invalidThe creation date provided is not valid or is in an incorrect format.
publish_date_invalidThe publish date provided is not valid or is in an incorrect format.