BUbuttondown
Subscribers

List Subscribers

Changed on

List all subscribers

get/subscribers

Request

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

Query parameters

bounce_date__endstring date

If provided, only return subscribers who last bounced on or before the given date.

bounce_date__startstring date

If provided, only return subscribers who last bounced on or after the given date.

bounce_reasonSubscriberUndeliverabilityReason[]

If provided, only return subscribers with the given bounce reason(s).

churn_date__endstring date

If provided, only return subscribers who churned on or before the given date.

churn_date__startstring date

If provided, only return subscribers who churned on or after the given date.

couponstring[]

If provided, only return subscribers with the given coupon ID(s).

current_pricestring[]

If provided, only return subscribers who are currently subscribed to the given price ID(s).

date__endstring date

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

date__startstring date

If provided, only return subscribers created on or after the given date.

domainstring[]

If provided, only return subscribers whose email domain matches the given domain(s).

[
  "gmail.com"
]
string
OR
string[]
expandstring[]

If provided, expand the given field. (Supported: 'stripe_customer', 'stripe_subscription'.)

formstring[]

If provided, only return subscribers that came through the given form(s).

[
  "form_abc123"
]
idsstring[]

If provided, only return subscribers with the given IDs.

ip_addressstring[]

If provided, only return subscribers with the given IP address(es).

last_click_date__endstring date

If provided, only return subscribers whose last click was on or before the given date.

last_click_date__startstring date

If provided, only return subscribers whose last click was on or after the given date.

last_open_date__endstring date

If provided, only return subscribers whose last open was on or before the given date.

last_open_date__startstring date

If provided, only return subscribers whose last open was on or after the given date.

-domainstring[]

If provided, only return subscribers whose email domain does not match the given domain(s).

[
  "gmail.com"
]
-tagstring

If provided, only return subscribers without the given tag.

Example:vip
-typeSubscriberType[]

If provided, only return subscribers without the given type.

orderingstring

The ordering to apply to the results.

Example:-creation_date
pricestring[]

If provided, only return subscribers who have at one point subscribed to the given price ID(s).

referral_codestring[]

If provided, only return subscribers with the given referral code(s).

referrer_urlstring[]

If provided, only return subscribers whose referrer URL(s) contain the given string.

open_rate__endnumber

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

open_rate__startnumber

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

click_rate__endnumber

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

click_rate__startnumber

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

risk_score__endnumber

If provided, only return subscribers with a risk score less than or equal to the given value.

risk_score__startnumber

If provided, only return subscribers with a risk score greater than or equal to the given value.

sourceSubscriberSource[]

If provided, only return subscribers with the given source(s).

[
  "api"
]
subscriber_importstring[]

If provided, only return subscribers that were imported by the given subscriber import.

[
  "import_abc123"
]
tagstring[]

If provided, only return subscribers with the given tag(s).

typeSubscriberType[]

If provided, only return subscribers with the given type.

[
  "regular"
]
undeliverability_date__endstring date

If provided, only return subscribers who became undeliverable on or before the given date.

undeliverability_date__startstring date

If provided, only return subscribers who became undeliverable on or after the given date.

undeliverability_reasonSubscriberUndeliverabilityReason[]

If provided, only return subscribers with the given undeliverability reason(s).

unsubscription_date__endstring date

If provided, only return subscribers who unsubscribed on or before the given date.

unsubscription_date__startstring date

If provided, only return subscribers who unsubscribed on or after the given date.

unsubscription_reasonstring[]

If provided, only return subscribers with the given unsubscription reason(s).

[
  "no longer interested"
]
upgrade_date__endstring date

If provided, only return subscribers who upgraded on or before the given date.

upgrade_date__startstring date

If provided, only return subscribers who upgraded on or after the given date.

utm_campaignstring[]

If provided, only return subscribers with the given UTM campaign(s).

[
  "paid_campaign_2024"
]
utm_mediumstring[]

If provided, only return subscribers with the given UTM medium(s).

[
  "paid_campaign_2024"
]
utm_sourcestring[]

If provided, only return subscribers with the given UTM source(s).

[
  "paid_campaign_2024"
]
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": [
    {
      "country": "US",
      "email_address": "telemachus@buttondown.email",
      "delivered_count": 12,
      "open_count": 7,
      "clicked_count": 3,
      "open_rate": 0.5833,
      "click_rate": 0.25
    }
  ]
}

Changes

  • 594190e20eb7Revision changes
    • warning

      added the new comment_text_contains_link enum value to the //// response property for the response status

  • 8fff9c6b1347Revision changes
    • info

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