Sign in

v4

latestOpenAPI 3.1.0MIT2026-08-02128224900.7 KB
Subscribers

List Subscribers

List all subscribers

get/subscribers

Query parameters

bounce_date__endstring date

If provided, only return subscribers who last bounced on or before the given 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.

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).

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.

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.

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).

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).

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.

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.

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).

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

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

If provided, only return subscribers whose email address contains the given string.

expandstring[]

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

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

formstring[]

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

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

[
  "form_abc123"
]
idsstring[]

If provided, only return subscribers with the given IDs.

If provided, only return subscribers with the given IDs.

ip_addressstring[]

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

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.

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.

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.

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.

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).

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

If provided, only return subscribers without the given tag.

-typeSubscriberType[]

If provided, only return subscribers without the given type.

If provided, only return subscribers without the given type.

orderingstring

The ordering to apply to the results.

Example:-creation_date

The ordering to apply to the results.

pricestring[]

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

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).

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.

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.

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.

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.

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.

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.

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.

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).

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.

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).

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

typeSubscriberType[]

If provided, only return subscribers with the given type.

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.

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.

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).

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.

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.

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).

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.

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.

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).

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).

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).

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

[
  "paid_campaign_2024"
]
pageinteger

The page number of the paginated response.

Example:1

The page number of the paginated response.

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
    }
  ]
}