Buttondown logo

Listing emails

Use the /emails endpoint to list all of your emails, including drafts, scheduled, and sent 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,
            "callouts": [],
            "attachments": [],
            "body": "I hope you really enjoy it!",
            "canonical_url": "",
            "commenting_mode": "enabled",
            "description": "",
            "archival_mode": "enabled",
            "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.

statusstring[] · enum

If provided, only return emails with the given status.

values
  • draft

    Draft emails are only visible to you and are not sent out to subscribers.

  • managed_by_rss

    This email was created by an external feed, and has not yet been finalized and sent out by Buttondown.

  • about_to_send

    This email has been queued to send out to subscribers, and will be sent automatically within a few minutes.

    If you're seeing that an email you just sent out is 'stuck' here, worry not — Buttondown sometimes takes a little bit longer to send out emails to ensure deliverability, but once it's marked as 'about to send' it will get sent out.

  • scheduled

    This email has been scheduled to send out to subscribers at a specific time. This specific time is available on the email as its publish_date.

  • in_flight

    This email is currently being sent out to subscribers, and is visible in your web archives if enabled.

    Some emails, especially those with large subscriber lists, may take a while to send out — Buttondown sends emails out in batches to ensure deliverability, so if you're seeing an email 'stuck' here, it's because our systems have detected that that's the optimal way to reach your subscribers.

  • paused

    This email has been paused, and is not visible in your web archives. If it is not resumed within seven days, it becomes a draft, sent, or partially sent email.

  • deleted

    This email has been deleted, and is no longer visible in your web archives.

  • errored

    This email has encountered an error while sending out to subscribers, and is not visible in your web archives.

  • sent

    This email has been sent out to subscribers, and is visible in your web archives if enabled.

  • partially_sent

    This email was paused while sending and was not resumed within seven days, so only some subscribers received it. It is not visible in your web archives.

  • imported

    This email was imported from another service, and is visible in your web archives if enabled.

  • throttled

    This email is in the process of being sent out, but is being intentionally sent slowly to ensure deliverability.

  • resending

    This email is in the process of automatically being resent to subscribers by Buttondown's systems in order to make sure all subscribers have received it.

  • transactional

    This email is a transactional email used by a core workflow in your newsletter or Automations, and is not visible in your web archives nor sent out to subscribers.

  • suppressed

    This email has been suppressed and is not visible to subscribers.

-statusstring[] · enum

If provided, only return emails without the given status.

values
  • draft

    Draft emails are only visible to you and are not sent out to subscribers.

  • managed_by_rss

    This email was created by an external feed, and has not yet been finalized and sent out by Buttondown.

  • about_to_send

    This email has been queued to send out to subscribers, and will be sent automatically within a few minutes.

    If you're seeing that an email you just sent out is 'stuck' here, worry not — Buttondown sometimes takes a little bit longer to send out emails to ensure deliverability, but once it's marked as 'about to send' it will get sent out.

  • scheduled

    This email has been scheduled to send out to subscribers at a specific time. This specific time is available on the email as its publish_date.

  • in_flight

    This email is currently being sent out to subscribers, and is visible in your web archives if enabled.

    Some emails, especially those with large subscriber lists, may take a while to send out — Buttondown sends emails out in batches to ensure deliverability, so if you're seeing an email 'stuck' here, it's because our systems have detected that that's the optimal way to reach your subscribers.

  • paused

    This email has been paused, and is not visible in your web archives. If it is not resumed within seven days, it becomes a draft, sent, or partially sent email.

  • deleted

    This email has been deleted, and is no longer visible in your web archives.

  • errored

    This email has encountered an error while sending out to subscribers, and is not visible in your web archives.

  • sent

    This email has been sent out to subscribers, and is visible in your web archives if enabled.

  • partially_sent

    This email was paused while sending and was not resumed within seven days, so only some subscribers received it. It is not visible in your web archives.

  • imported

    This email was imported from another service, and is visible in your web archives if enabled.

  • throttled

    This email is in the process of being sent out, but is being intentionally sent slowly to ensure deliverability.

  • resending

    This email is in the process of automatically being resent to subscribers by Buttondown's systems in order to make sure all subscribers have received it.

  • transactional

    This email is a transactional email used by a core workflow in your newsletter or Automations, and is not visible in your web archives nor sent out to subscribers.

  • suppressed

    This email has been suppressed and is not visible to subscribers.

idsarray

If provided, only return emails with the given IDs.

orderingstring

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_datedate

Filter results by date range. Provide one or more of the following query parameters:

  • creation_date__start (date, on or after (inclusive)): If provided, only return emails created after the given date.
  • creation_date__end (date, on or before (inclusive)): If provided, only return emails created before the given date.

publish_datedate

Filter results by date range. Provide one or more of the following query parameters:

  • publish_date__start (date, on or after (inclusive)): If provided, only return emails published after the given date.
  • publish_date__end (date, on or before (inclusive)): If provided, only return emails published before the given date.

excluded_fieldsstring[] · enum

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

values
  • body

sourcestring[] · enum

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

values
  • api

    This email was created via the API.

  • import

    This email was imported from another service.

  • app

    This email was created via the Buttondown web app.

  • external_feed

    This email was created by an external RSS feed.

  • smtp

    This email was created by emailing it in to Buttondown (post by email / SMTP).

archival_modestring[] · enum

If provided, only return emails with the given archival mode.

values
  • archive_only

    This email is visible in the archive to everyone, but is not email content (e.g. an imported blog post) and is never sent or shown in email-rendering contexts.

  • disabled

    This email is not visible in the archive.

  • enabled

    This email is visible in the archive to everyone.

  • enabled_for_paid_subscribers

    This email is visible in the archive to paid subscribers only.

  • enabled_for_subscribers

    This email is visible in the archive to subscribers only.

email_typestring[] · enum

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

values
  • public

    Public emails are sent out to all of your subscribers and are available in your web archives.

  • private

    Private emails are sent out to all of your subscribers but are not viewable in your web archives.

  • premium

    Premium emails are sent out to only paying subscribers (including those with gift subscriptions or on a free trial), and only premium subscribers can view them in online archives.

  • free

    Free emails are sent out only to subscribers who are not paying for your newsletter (so you can send specific emails to convince them to pay, for instance!)

  • churned

    Emails sent specifically to subscribers who were previously premium but have since churned.

  • archival

    Emails that are only available in the archive and not sent to subscribers.

subjectstring

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

attachmentsarray

If provided, only return emails with the given attachments.

snippet_idarray

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

deliveries__startstring

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

deliveries__endstring

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

click_rate__startstring

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

click_rate__endstring

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

open_rate__startstring

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

open_rate__endstring

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

pagestring

The page number of the paginated response.