--- title: "List Subscribers" method: GET path: "/subscribers" tags: ["Subscribers"] --- # List Subscribers `GET /subscribers` List all subscribers ## Query parameters - `bounce_date__end` string, date — If provided, only return subscribers who last bounced on or before the given date. - `bounce_date__start` string, date — If provided, only return subscribers who last bounced on or after the given date. - `bounce_reason` SubscriberUndeliverabilityReason[] — If provided, only return subscribers with the given bounce reason(s). - `churn_date__end` string, date — If provided, only return subscribers who churned on or before the given date. - `churn_date__start` string, date — If provided, only return subscribers who churned on or after the given date. - `coupon` string[] — If provided, only return subscribers with the given coupon ID(s). - `current_price` string[] — If provided, only return subscribers who are currently subscribed to the given price ID(s). - `date__end` string, date — If provided, only return subscribers created before the given date. - `date__start` string, date — If provided, only return subscribers created on or after the given date. - `domain` string[] — If provided, only return subscribers whose email domain matches the given domain(s). - `email_address` union — If provided, only return subscribers whose email address contains the given string. - string - string[] - `expand` string[] — If provided, expand the given field. (Supported: 'stripe_customer', 'stripe_subscription'.) - `form` string[] — If provided, only return subscribers that came through the given [form(s)](https://docs.buttondown.com/registration-forms). - `ids` string[] — If provided, only return subscribers with the given IDs. - `ip_address` string[] — If provided, only return subscribers with the given IP address(es). - `last_click_date__end` string, date — If provided, only return subscribers whose last click was on or before the given date. - `last_click_date__start` string, date — If provided, only return subscribers whose last click was on or after the given date. - `last_open_date__end` string, date — If provided, only return subscribers whose last open was on or before the given date. - `last_open_date__start` string, date — If provided, only return subscribers whose last open was on or after the given date. - `-domain` string[] — If provided, only return subscribers whose email domain does not match the given domain(s). - `-tag` string — If provided, only return subscribers without the given [tag](https://docs.buttondown.com/api-tags-introduction). - `-type` SubscriberType[] — If provided, only return subscribers without the given type. - `ordering` string — The ordering to apply to the results. - `price` string[] — If provided, only return subscribers who have at one point subscribed to the given price ID(s). - `referral_code` string[] — If provided, only return subscribers with the given referral code(s). - `referrer_url` string[] — If provided, only return subscribers whose referrer URL(s) contain the given string. - `open_rate__end` number — If provided, only return subscribers with an open rate less than or equal to the given value. - `open_rate__start` number — If provided, only return subscribers with an open rate greater than or equal to the given value. - `click_rate__end` number — If provided, only return subscribers with a click rate less than or equal to the given value. - `click_rate__start` number — If provided, only return subscribers with a click rate greater than or equal to the given value. - `risk_score__end` number — If provided, only return subscribers with a [risk score](https://docs.buttondown.com/firewall) less than or equal to the given value. - `risk_score__start` number — If provided, only return subscribers with a [risk score](https://docs.buttondown.com/firewall) greater than or equal to the given value. - `source` SubscriberSource[] — If provided, only return subscribers with the given source(s). - `subscriber_import` string[] — If provided, only return subscribers that were imported by the given subscriber import. - `tag` string[] — If provided, only return subscribers with the given [tag(s)](https://docs.buttondown.com/api-tags-introduction). - `type` SubscriberType[] — If provided, only return subscribers with the given type. - `undeliverability_date__end` string, date — If provided, only return subscribers who became undeliverable on or before the given date. - `undeliverability_date__start` string, date — If provided, only return subscribers who became undeliverable on or after the given date. - `undeliverability_reason` SubscriberUndeliverabilityReason[] — If provided, only return subscribers with the given undeliverability reason(s). - `unsubscription_date__end` string, date — If provided, only return subscribers who unsubscribed on or before the given date. - `unsubscription_date__start` string, date — If provided, only return subscribers who unsubscribed on or after the given date. - `unsubscription_reason` string[] — If provided, only return subscribers with the given unsubscription reason(s). - `upgrade_date__end` string, date — If provided, only return subscribers who upgraded on or before the given date. - `upgrade_date__start` string, date — If provided, only return subscribers who upgraded on or after the given date. - `utm_campaign` string[] — If provided, only return subscribers with the given UTM campaign(s). - `utm_medium` string[] — If provided, only return subscribers with the given UTM medium(s). - `utm_source` string[] — If provided, only return subscribers with the given UTM source(s). - `page` integer — The page number of the paginated response. ## Response `200` OK - SubscriberPage - `results` Subscriber[], required — The list of results for this page. - `id` string, required — A unique TypeID associated with the object. - `creation_date` string, date-time, required — The date and time at which the object was first created. - `avatar_url` string, nullable — URL of the subscriber's avatar image (e.g. a Gravatar URL), if available. - `bounce_date` string, date-time, nullable — The date of the subscriber's most recent bounce event. May be set even if the subscriber has not yet been marked as undeliverable. - `bounce_reason` 'access_denied' | 'authentication_issue' | 'delivery_expired' | 'domain_blocked' | 'email_blocked' | 'hard_bounce' | 'ip_blocked' | 'ip_undeliverable' | 'malformed' | 'on_esp_denylist' | 'other' | 'out_of_storage' | 'problematic_url' | 'rate_limited' | 'spam' | 'transient' | 'disabled' | 'does_not_exist' | 'spf_failed' | 'unreachable' — The reason Buttondown has marked the subscriber as undeliverable. Undeliverable subscribers are not sent emails, and may be periodically removed from the system (or restored, if the reason is no longer valid.) These reasons are grouped into three categories: - PermanentFailure ("Failed (recipient)"): Address-based issues where the recipient is truly unreachable. Includes: HARD_BOUNCE - MessageFailure ("Failed (message)"): Message/sender problems where future emails may succeed. Includes: ACCESS_DENIED, AUTHENTICATION_ISSUE, DELIVERY_EXPIRED, DOMAIN_BLOCKED, EMAIL_BLOCKED, IP_BLOCKED, ON_ESP_DENYLIST, OUT_OF_STORAGE, PROBLEMATIC_URL, SPAM - Deferral (not shown to customers): Transient delivery issues that will be retried. Includes: RATE_LIMITED, TRANSIENT - `churn_date` string, date-time, nullable — When the subscriber cancelled their paid subscription, if applicable. - `commenting_disabled` boolean — Whether this subscriber is prevented from commenting. - `country` string, nullable — The ISO 3166-1 alpha-2 country code inferred from the subscriber's IP address at signup, if available. - `email_address` string, required — The email address of the subscriber. - `gift_subscription_end_date` string, date-time, nullable — When the subscriber's gift subscription expires, if applicable. - `gift_subscription_message` string, nullable — A custom message that was sent to the subscriber when the gift subscription was created. - `ip_address` string, nullable — The IP address recorded when the subscriber signed up, if available. - `last_click_date` string, date-time, nullable — When the subscriber most recently clicked a link in an email. - `last_open_date` string, date-time, nullable — When the subscriber most recently opened an email. - `delivered_count` integer, nullable — The number of distinct emails — both broadcasts and automation sends — delivered to this subscriber. Cached and refreshed periodically, so it may lag recent activity. - `open_count` integer, nullable — The subscriber's open count. - `clicked_count` integer, nullable — The subscriber's clicked count. - `open_rate` number, nullable — The subscriber's open rate, computed from engagement counts. Null if delivered_count is 0 or null. - `click_rate` number, nullable — The subscriber's click rate, computed from engagement counts. Null if delivered_count is 0 or null. - `metadata` object — A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested — you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata)) - `notes` string — Any notes you want to attach to the subscriber. These are not publicly visible. - `purchased_by` string, nullable — The email address of the individual who purchased this subscription on behalf of the subscriber. - `purchased_message` string, nullable — A custom message that was sent to the subscriber when the subscription was purchased on behalf of the subscriber. - `referral_code` string, required — The subscriber's unique referral code, used to attribute referred signups. - `referrer_url` string — The URL the subscriber was referred from (e.g. where they submitted the subscription form). - `risk_score` number, nullable — The risk score of the subscriber. Positive numbers represent a higher risk; negative numbers represent a lower risk. - `secondary_id` integer, required — A human-readable sequential identifier, unique within the newsletter. - `source` 'admin' | 'api' | 'carrd' | 'comment' | 'embedded_form' | 'form' | 'import' | 'memberful' | 'netlify' | 'organic' | 'patreon' | 'shopify' | 'stripe' | 'user' | 'zapier', required — Represents the original provenance of a subscriber. This value is not exposed to subscribers; it's only used for internal tracking purposes and governs some of the behavior of the subscriber (i.e. whether or not to require double opt-in.) - `stripe_coupon` StripeCoupon — Coupons let you offer discounts to subscribers who pay for your newsletter. Buttondown's coupons are backed by Stripe, so each coupon maps to a coupon on your connected Stripe account. Use them to run promotions—for example, a percentage off a paid subscription. - `coupon_id` string, required — The Stripe coupon ID (e.g. `coupon_...`). - `percent_off` string, nullable — The percentage discount applied by the coupon, if any. - `amount_off` integer, nullable — The fixed amount discount applied by the coupon, in the smallest currency unit (e.g. cents), if any. - `name` string, nullable — The display name of the coupon. - `stripe_customer_id` string, nullable — The Stripe customer ID associated with the subscriber, if any. - `subscriber_import_id` string, nullable — The ID of the [subscriber import](https://docs.buttondown.com/importing-subscribers) that created this subscriber, if any. - `tags` string[], required — A list of [tag](https://docs.buttondown.com/api-tags-introduction) names applied to the subscriber. Tags that don't already exist will be created, which requires a plan that includes tags (Basic or higher). - `transitions` Transition[] — The history of subscriber type transitions (e.g. `regular` → `premium`). - `date` string, date-time, required — When the subscriber transitioned to `type`. - `type` 'blocked' | 'complained' | 'churning' | 'churned' | 'gifted' | 'unactivated' | 'unpaid' | 'undeliverable' | 'premium' | 'past_due' | 'paused' | 'regular' | 'removed' | 'trialed' | 'unsubscribed' | 'upcoming', required — Represents the state of a subscriber and what emails they should or should not be receiving. This type is meant to be fully expressive so as to consolidate the logic of determining what emails a subscriber should receive into a single place. Note that the only types that can be set programmatically are REGULAR, UNSUBSCRIBED, GIFTED and UNPAID. All other types are meant to be user-visible and cannot be set programmatically. - `email_transitions` EmailTransition[] — The history of email address changes for this subscriber. - `date` string, date-time, required — When the email address change took effect. - `old_email_address` string, nullable — The subscriber's previous email address, or null for the initial address. - `new_email_address` string, required — The subscriber's email address after the transition. - `form_id` string, nullable — The ID of the [registration form](https://docs.buttondown.com/registration-forms) the subscriber signed up through, if any. - `firewall_reasons` FirewallReason[] — Information collected by Buttondown's firewall about this subscriber. See [the firewall](https://docs.buttondown.com/firewall) for more information. - `code` 'email_address_capital_letters' | 'email_address_cleantalk_score' | 'email_address_contains_prohibited_string' | 'email_address_domain_burst' | 'email_address_esp_suppression' | 'email_address_extant_subscriber_count' | 'email_address_gmail_word_numbers' | 'email_address_has_gravatar' | 'email_address_is_honeypot' | 'email_address_length' | 'email_address_local_part_has_many_periods' | 'email_address_many_consonants_in_a_row' | 'email_address_mx_record_is_valid' | 'email_address_noreply_local_part' | 'email_address_null_characters' | 'email_address_peaceful_domain' | 'email_address_plus_single_number' | 'email_address_plus_variant_accounts' | 'email_address_previous_evaluation' | 'email_address_prohibited_via_domain' | 'email_address_regex' | 'email_address_sandbox_test' | 'email_address_shannon_entropy' | 'email_address_tied_to_account' | 'email_address_typo' | 'embedded_form_honeypot' | 'fingerprint_missing' | 'ip_address_cleantalk_score' | 'ip_address_country_risk' | 'ip_address_datacenter' | 'ip_address_extant_subscriber_count' | 'ip_address_peaceful' | 'ip_address_previous_evaluation' | 'ip_address_prohibited' | 'metadata_has_garbage' | 'newsletter_age' | 'newsletter_has_customized_transactional_email' | 'newsletter_has_prohibited_string' | 'newsletter_status' | 'project_honeypot' | 'referrer_url_prohibited' | 'registration_without_prior_page_visit' | 'subscriber_import_provenance' | 'subscriber_import_source' | 'text_contains_malicious_url' | 'text_contains_prohibited_string' | 'turnstile_response_token_is_valid' | 'user_agent_known' | 'username_shannon_entropy', required — An enumeration. - `reason` string, required — Human-readable explanation for why we flagged the subscriber. - `type` 'blocked' | 'complained' | 'churning' | 'churned' | 'gifted' | 'unactivated' | 'unpaid' | 'undeliverable' | 'premium' | 'past_due' | 'paused' | 'regular' | 'removed' | 'trialed' | 'unsubscribed' | 'upcoming', required — Represents the state of a subscriber and what emails they should or should not be receiving. This type is meant to be fully expressive so as to consolidate the logic of determining what emails a subscriber should receive into a single place. Note that the only types that can be set programmatically are REGULAR, UNSUBSCRIBED, GIFTED and UNPAID. All other types are meant to be user-visible and cannot be set programmatically. - `undeliverability_date` string, date-time, nullable — When the subscriber was marked as undeliverable, if applicable. - `undeliverability_reason` 'access_denied' | 'authentication_issue' | 'delivery_expired' | 'domain_blocked' | 'email_blocked' | 'hard_bounce' | 'ip_blocked' | 'ip_undeliverable' | 'malformed' | 'on_esp_denylist' | 'other' | 'out_of_storage' | 'problematic_url' | 'rate_limited' | 'spam' | 'transient' | 'disabled' | 'does_not_exist' | 'spf_failed' | 'unreachable' — The reason Buttondown has marked the subscriber as undeliverable. Undeliverable subscribers are not sent emails, and may be periodically removed from the system (or restored, if the reason is no longer valid.) These reasons are grouped into three categories: - PermanentFailure ("Failed (recipient)"): Address-based issues where the recipient is truly unreachable. Includes: HARD_BOUNCE - MessageFailure ("Failed (message)"): Message/sender problems where future emails may succeed. Includes: ACCESS_DENIED, AUTHENTICATION_ISSUE, DELIVERY_EXPIRED, DOMAIN_BLOCKED, EMAIL_BLOCKED, IP_BLOCKED, ON_ESP_DENYLIST, OUT_OF_STORAGE, PROBLEMATIC_URL, SPAM - Deferral (not shown to customers): Transient delivery issues that will be retried. Includes: RATE_LIMITED, TRANSIENT - `unsubscription_date` string, date-time, nullable — When the subscriber unsubscribed, if applicable. - `unsubscription_reason` string, nullable — Free-text reason the subscriber unsubscribed, if provided. - `upgrade_date` string, date-time, nullable — When the subscriber upgraded to a paid subscription, if applicable. - `utm_campaign` string, required — The UTM campaign the subscriber was attributed to at signup. - `utm_medium` string, required — The UTM medium the subscriber was attributed to at signup. - `utm_source` string, required — The UTM source the subscriber was attributed to at signup. - `stripe_customer` object, nullable — If expanded, the Stripe customer associated with this subscriber. - `stripe_subscription` object, nullable — If expanded, the Stripe subscription backing this subscriber's paid subscription. - `next` string, nullable — The URL to the next page of results, if any. - `previous` string, nullable — The URL to the previous page of results, if any. - `count` integer, required — The total number of results across all pages. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `409` — Conflict - `422` — Unprocessable Entity - `429` — Too Many Requests --- [API](https://skmtc.net/buttondown/apis/buttondown-api.md) · [All operations](https://skmtc.net/buttondown/apis/buttondown-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/buttondown/buttondown-api/versions/3a702c095d22/schema)