Buttondown logo

Listing subscribers

Use the /subscribers endpoint to list all of your subscribers.

Sample requests

These sample requests are autogenerated by the OpenAPI spec.

import requests

url = "https://api.buttondown.com/v1/subscribers"
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": "sub_0k28edc3fw896bp4mrhc535z5k",
            "creation_date": "2020-09-29T00:00:00+00:00",
            "avatar_url": "",
            "bounce_date": null,
            "bounce_reason": null,
            "churn_date": null,
            "commenting_disabled": false,
            "country": null,
            "email_address": "telemachus@buttondown.email",
            "gift_subscription_end_date": null,
            "gift_subscription_message": "",
            "ip_address": null,
            "last_click_date": null,
            "last_open_date": null,
            "delivered_count": null,
            "open_count": null,
            "clicked_count": null,
            "open_rate": null,
            "click_rate": null,
            "metadata": {
                "name": "Telemachus"
            },
            "notes": "",
            "purchased_by": null,
            "purchased_message": null,
            "referral_code": "",
            "referrer_url": "",
            "risk_score": null,
            "secondary_id": 1,
            "source": "organic",
            "stripe_coupon": null,
            "stripe_customer_id": null,
            "subscriber_import_id": null,
            "tags": [],
            "transitions": [],
            "email_transitions": [],
            "form_id": null,
            "firewall_reasons": [],
            "type": "unactivated",
            "undeliverability_date": null,
            "undeliverability_reason": null,
            "unsubscription_date": null,
            "unsubscription_reason": "",
            "upgrade_date": null,
            "utm_campaign": "",
            "utm_medium": "",
            "utm_source": "",
            "stripe_customer": null,
            "stripe_subscription": null
        }
    ],
    "count": 1
}

Path parameters

Consult the Filtering documentation for more information on how to filter and sort your requests.

bounce_datedate

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

  • bounce_date__end (date, on or before (inclusive)): If provided, only return subscribers who last bounced on or before the given date.
  • bounce_date__start (date, on or after (inclusive)): If provided, only return subscribers who last bounced on or after the given date.

bounce_reasonstring[] · enum

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

values
  • access_denied

    Access to the subscriber's email was denied.

  • authentication_issue

    The email failed authentication checks (DMARC, SPF, or relay permissions).

  • delivery_expired

    The delivery attempt timed out before the email could be delivered.

  • domain_blocked

    The subscriber's domain is blocked.

  • email_blocked

    The subscriber's email address is blocked.

  • hard_bounce

    The subscriber's email address permanently bounced (the address does not exist or is unreachable).

  • ip_blocked

    The subscriber's IP address is blocked.

  • ip_undeliverable

    The subscriber's IP address is undeliverable.

  • malformed

    The subscriber's email is malformed.

  • on_esp_denylist

    The subscriber's email is on an ESP denylist.

  • other

    The subscriber is deemed undeliverable for an unknown reason.

  • out_of_storage

    The subscriber's mailbox is out of storage.

  • problematic_url

    The email contained a problematic URL.

  • rate_limited

    The email provider, i.e. Gmail, acknowledges the message, but is temporarily refusing to send the message due to overall volume coming from the sender. Sender can mean a number of different things. For instance, it can mean that your specific newsletter is sending a high amount of volume. It can mean your domain is sending a high amount of volume. Or, in rare cases, it can mean that Buttondown itself as an overall system is sending too much volume. You do not need to change or retry any errors you see due to rate limiting. Buttondown will automatically handle that. However, if you see this error come up often, consider more regularly sending your email at a specific cadence, i.e. weekly.

  • spam

    The email was marked as spam.

  • transient

    The email encountered a temporary delivery issue and will be retried automatically.

  • disabled

    The subscriber's email account is disabled.

  • does_not_exist

    The subscriber's email does not exist.

  • spf_failed

    SPF validation failed for the email.

  • unreachable

    The subscriber's email is unreachable.

churn_datedate

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

  • churn_date__end (date, on or before (inclusive)): If provided, only return subscribers who churned on or before the given date.
  • churn_date__start (date, on or after (inclusive)): If provided, only return subscribers who churned on or after the given date.

couponarray

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

current_pricearray

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

datedate

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

  • date__end (date, on or before (inclusive)): If provided, only return subscribers created before the given date.
  • date__start (date, on or after (inclusive)): If provided, only return subscribers created on or after the given date.

domainarray

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

email_addressstring

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

expandarray

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

formarray

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

idsarray

If provided, only return subscribers with the given IDs.

ip_addressarray

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

last_click_datedate

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

  • last_click_date__end (date, on or before (inclusive)): If provided, only return subscribers whose last click was on or before the given date.
  • last_click_date__start (date, on or after (inclusive)): If provided, only return subscribers whose last click was on or after the given date.

last_open_datedate

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

  • last_open_date__end (date, on or before (inclusive)): If provided, only return subscribers whose last open was on or before the given date.
  • last_open_date__start (date, on or after (inclusive)): If provided, only return subscribers whose last open was on or after the given date.

-domainarray

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

-tagstring

If provided, only return subscribers without the given tag.

-typestring[] · enum

If provided, only return subscribers without the given type.

values
  • blocked

    Subscribers that were automatically blocked from signing up for your newsletter by Buttondown's automated filtering systems. You can review the subscriber's email address and make a decision about whether to allow them to subscribe.

  • complained

    Subscribers that have registered a complaint with their email provider. Buttondown will not try to send them any future emails; no action is required on your part.

  • churning

    Subscribers who have elected to not renew their subscription to your newsletter and will become unpaid subscribers at the end of their current billing period.

  • churned

    Subscribers which were previously premium subscribers, but have since churned but are not unsubscribed. These subscribers receive public emails as well as teasers.

  • gifted

    Subscribers that have been gifted free premium subscriptions.

  • unactivated

    Subscribers who have not yet confirmed their email or opted in.

  • unpaid

    Subscribers who have not yet purchased a subscription to your newsletter. Subscribers will only be marked as unpaid if you have turned off free subscriptions to your paid newsletter; otherwise, they will be marked as Regular.

  • undeliverable

    Buttondown marks subscribers as undeliverable when we receive some sort of proof that this address does not exist, such as a suppression notification from one of our email providers or a hard bounce from the host or mailbox itself. We don't try to deliver email to subscribers marked as undeliverable, but you can, in some cases, change their email address (e.g. if they've changed their email address in your CRM, or if you had a typo in their email address) to try and fix things.

  • premium

    Subscribers with active premium subscriptions.

  • past_due

    Subscribers who technically have active paid subscriptions, but have not paid their invoices in time.

  • paused

    Subscribers that are on a temporary hold from their premium subscription, but are still subscribed to your newsletter.

  • regular

    Normal subscribers who have not unsubscribed or deactivated in any way.

  • removed

    Subscribers that you have banned from your newsletter. This is not the same as unsubscribed: those subscribers removed themselves.

  • trialed

    Subscribers that are temporarily receiving a premium subscription to your newsletter.

  • unsubscribed

    Subscribers that have or have been unsubscribed from your newsletter.

  • upcoming

    Subscribers who have a premium subscription starting in the future.

orderingstring

The ordering to apply to the results.

pricearray

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

referral_codearray

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

referrer_urlarray

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

open_rate__endstring

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

open_rate__startstring

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

click_rate__endstring

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

click_rate__startstring

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

risk_score__endstring

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

risk_score__startstring

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

sourcestring[] · enum

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

values
  • admin

    This subscriber was added by a member of Buttondown support staff.

  • api

    Subscriber created by API.

  • carrd

    This subscriber joined via Carrd.

  • comment

    This subscriber joined via commenting on an email.

  • embedded_form

    This subscriber subscribed via an embedded form.

  • form

    This subscriber subscribed via a Buttondown form.

  • import

    This subscriber was imported from another service.

  • memberful

    This subscriber joined via Memberful.

  • netlify

    This subscriber joined via Netlify.

  • organic

    This subscriber subscribed to your newsletter of their own volition.

  • patreon

    This subscriber joined via Patreon.

  • shopify

    This subscriber joined via Shopify.

  • stripe

    This subscriber joined via Stripe.

  • user

    This subscriber was added by a user with write permissions for subscribers within the Buttondown dashboard.

  • zapier

    This subscriber joined via Zapier.

subscriber_importarray

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

tagarray

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

typestring[] · enum

If provided, only return subscribers with the given type.

values
  • blocked

    Subscribers that were automatically blocked from signing up for your newsletter by Buttondown's automated filtering systems. You can review the subscriber's email address and make a decision about whether to allow them to subscribe.

  • complained

    Subscribers that have registered a complaint with their email provider. Buttondown will not try to send them any future emails; no action is required on your part.

  • churning

    Subscribers who have elected to not renew their subscription to your newsletter and will become unpaid subscribers at the end of their current billing period.

  • churned

    Subscribers which were previously premium subscribers, but have since churned but are not unsubscribed. These subscribers receive public emails as well as teasers.

  • gifted

    Subscribers that have been gifted free premium subscriptions.

  • unactivated

    Subscribers who have not yet confirmed their email or opted in.

  • unpaid

    Subscribers who have not yet purchased a subscription to your newsletter. Subscribers will only be marked as unpaid if you have turned off free subscriptions to your paid newsletter; otherwise, they will be marked as Regular.

  • undeliverable

    Buttondown marks subscribers as undeliverable when we receive some sort of proof that this address does not exist, such as a suppression notification from one of our email providers or a hard bounce from the host or mailbox itself. We don't try to deliver email to subscribers marked as undeliverable, but you can, in some cases, change their email address (e.g. if they've changed their email address in your CRM, or if you had a typo in their email address) to try and fix things.

  • premium

    Subscribers with active premium subscriptions.

  • past_due

    Subscribers who technically have active paid subscriptions, but have not paid their invoices in time.

  • paused

    Subscribers that are on a temporary hold from their premium subscription, but are still subscribed to your newsletter.

  • regular

    Normal subscribers who have not unsubscribed or deactivated in any way.

  • removed

    Subscribers that you have banned from your newsletter. This is not the same as unsubscribed: those subscribers removed themselves.

  • trialed

    Subscribers that are temporarily receiving a premium subscription to your newsletter.

  • unsubscribed

    Subscribers that have or have been unsubscribed from your newsletter.

  • upcoming

    Subscribers who have a premium subscription starting in the future.

undeliverability_datedate

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

  • undeliverability_date__end (date, on or before (inclusive)): If provided, only return subscribers who became undeliverable on or before the given date.
  • undeliverability_date__start (date, on or after (inclusive)): If provided, only return subscribers who became undeliverable on or after the given date.

undeliverability_reasonstring[] · enum

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

values
  • access_denied

    Access to the subscriber's email was denied.

  • authentication_issue

    The email failed authentication checks (DMARC, SPF, or relay permissions).

  • delivery_expired

    The delivery attempt timed out before the email could be delivered.

  • domain_blocked

    The subscriber's domain is blocked.

  • email_blocked

    The subscriber's email address is blocked.

  • hard_bounce

    The subscriber's email address permanently bounced (the address does not exist or is unreachable).

  • ip_blocked

    The subscriber's IP address is blocked.

  • ip_undeliverable

    The subscriber's IP address is undeliverable.

  • malformed

    The subscriber's email is malformed.

  • on_esp_denylist

    The subscriber's email is on an ESP denylist.

  • other

    The subscriber is deemed undeliverable for an unknown reason.

  • out_of_storage

    The subscriber's mailbox is out of storage.

  • problematic_url

    The email contained a problematic URL.

  • rate_limited

    The email provider, i.e. Gmail, acknowledges the message, but is temporarily refusing to send the message due to overall volume coming from the sender. Sender can mean a number of different things. For instance, it can mean that your specific newsletter is sending a high amount of volume. It can mean your domain is sending a high amount of volume. Or, in rare cases, it can mean that Buttondown itself as an overall system is sending too much volume. You do not need to change or retry any errors you see due to rate limiting. Buttondown will automatically handle that. However, if you see this error come up often, consider more regularly sending your email at a specific cadence, i.e. weekly.

  • spam

    The email was marked as spam.

  • transient

    The email encountered a temporary delivery issue and will be retried automatically.

  • disabled

    The subscriber's email account is disabled.

  • does_not_exist

    The subscriber's email does not exist.

  • spf_failed

    SPF validation failed for the email.

  • unreachable

    The subscriber's email is unreachable.

unsubscription_datedate

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

  • unsubscription_date__end (date, on or before (inclusive)): If provided, only return subscribers who unsubscribed on or before the given date.
  • unsubscription_date__start (date, on or after (inclusive)): If provided, only return subscribers who unsubscribed on or after the given date.

unsubscription_reasonarray

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

upgrade_datedate

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

  • upgrade_date__end (date, on or before (inclusive)): If provided, only return subscribers who upgraded on or before the given date.
  • upgrade_date__start (date, on or after (inclusive)): If provided, only return subscribers who upgraded on or after the given date.

utm_campaignarray

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

utm_mediumarray

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

utm_sourcearray

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

pagestring

The page number of the paginated response.