BUbuttondown
Emails

List Emails

Changed on

List all emails

get/emails

Request

  • Base URL
    https://api.buttondown.com/v1
  • URL
    https://api.buttondown.com/v1/emails
  • Auth
    API key in header Authorization

Query parameters

statusEmailStatus[]

If provided, only return emails with the given status.

-statusEmailStatus[]

If provided, only return emails without the given status.

[
  "draft"
]
idsstring[]

If provided, only return emails with the given IDs.

ordering'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'

The ordering to apply to the results.

Example:-publish_date
creation_date__startstring date

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

creation_date__endstring date

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

publish_date__startstring date

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

publish_date__endstring date

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

excluded_fieldsEmailExcludableField[]

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

[
  "body"
]
sourceEmailSource[]

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

[
  "api"
]
archival_modeArchivalMode[]

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

email_typeEmailType[]

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

subjectstring

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

image_idstring[]

If provided, only return emails whose body uses one of the given images.

[
  "img_01h8xg4j3k2m1n0p9q8r7s6t5v"
]
attachmentsstring[]

If provided, only return emails with the given attachments.

snippet_idstring[]

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

deliveries__startinteger

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

Example:100
deliveries__endinteger

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

Example:1000
click_rate__startnumber

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

Example:0.1
click_rate__endnumber

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

Example:0.5
open_rate__startnumber

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

Example:0.2
open_rate__endnumber

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

Example:0.8
pageinteger

The page number of the paginated response.

Example:1

Response

OK

nextstring nullable

The URL to the next page of results, if any.

previousstring nullable

The URL to the previous page of results, if any.

countinteger required

The total number of results across all pages.

Example response

{
  "results": [
    {
      "slug": "welcome-to-the-newsletter"
    }
  ]
}

Changes

  • 3c93095b1b8aRevision changes
    • info

      added the new optional query request parameter image_id

  • 8fff9c6b1347Revision changes
    • breaking

      removed the enum value suppressed from the property items/ of the query request parameter -status

    • breaking

      removed the enum value suppressed from the property items/ of the query request parameter status

    • warning

      removed the optional property // from the response with the status

    • info

      removed the suppressed enum value from the // response property for the response status