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": [
        {
            "id": "em_29fxqcmrkp969vzttksexvmvr8",
            "creation_date": "2000-01-01T00:00:00+00:00",
            "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",
            "review_mode": "disabled",
            "description": "",
            "email_type": "public",
            "featured": false,
            "filters": {
                "filters": [],
                "groups": [],
                "predicate": "and"
            },
            "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.

-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
Description

The ordering to apply to the results.

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
[]
Description

If provided, exclude the given field(s) from the response. This can improve performance for large responses.

source

Type
EmailSource[]
Description

If provided, only return emails from the given source(s).

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.

snippet_id

Type
array
Description

If provided, only return emails that reference the given snippets.

deliveries__start

Type
string
Description

If provided, only return emails with at least this many deliveries.

deliveries__end

Type
string
Description

If provided, only return emails with at most this many deliveries.

click_rate__start

Type
string
Description

If provided, only return emails with a click rate greater than or equal to the given value.

click_rate__end

Type
string
Description

If provided, only return emails with a click rate less than or equal to the given value.

open_rate__start

Type
string
Description

If provided, only return emails with an open rate greater than or equal to the given value.

open_rate__end

Type
string
Description

If provided, only return emails with an open rate less than or equal to the given value.