Buttondown Documentation

Buttondown Documentation

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook

Listing 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": "13121cd6-0dfc-424c-bb12-988b0a32fcb3",
            "creation_date": "2020-09-29T00:00:00+00:00",
            "email_address": "telemachus@buttondown.email",
            "notes": "",
            "metadata": {
                "name": "Telemachus"
            },
            "tags": [],
            "referrer_url": "",
            "secondary_id": 1,
            "type": "unactivated",
            "source": "organic",
            "utm_campaign": "",
            "utm_medium": "",
            "utm_source": "",
            "referral_code": "",
            "avatar_url": "",
            "stripe_coupon": null,
            "unsubscription_date": null,
            "churn_date": null,
            "undeliverability_date": null,
            "undeliverability_reason": null,
            "upgrade_date": null,
            "unsubscription_reason": "",
            "transitions": [],
            "ip_address": null,
            "last_open_date": null,
            "last_click_date": null,
            "stripe_customer_id": null,
            "subscriber_import_id": null,
            "risk_score": null,
            "stripe_customer": null
        }
    ],
    "count": 1
}

Path parameters

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

type

Type
SubscriberType[]
Description

If provided, only return subscribers with the given type.

-type

Type
SubscriberType[]
Description

If provided, only return subscribers without the given type.

ids

Type
array
Description

If provided, only return subscribers with the given IDs.

email_address

Type
string
Description

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

tag

Type
array

-tag

Type
string

ordering

Type
string

price

Type
array
Description

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

coupon

Type
array
Description

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

referral_code

Type
array
Description

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

date__start

Type
string
Description

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

date__end

Type
string
Description

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

last_open_date__start

Type
string
Description

If provided, only return subscribers with the given last open date(s).

last_open_date__end

Type
string
Description

If provided, only return subscribers with the given last open date(s).

last_click_date__start

Type
string
Description

If provided, only return subscribers with the given last click date(s).

last_click_date__end

Type
string
Description

If provided, only return subscribers with the given last click date(s).

subscriber_import

Type
array
Description

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

expand

Type
array
Description

If provided, expand the given field. (Only supported fields: 'stripe_customer')

ip_address

Type
array
Description

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

upgrade_date__start

Type
string
Description

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

upgrade_date__end

Type
string
Description

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

undeliverability_date__start

Type
string
Description

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

undeliverability_date__end

Type
string
Description

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

undeliverability_reason

Type
SubscriberUndeliverabilityReason[]
Description

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

unsubscription_reason

Type
array
Description

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

referrer_url

Type
array
Description

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

utm_source

Type
array
Description

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

utm_campaign

Type
array
Description

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

utm_medium

Type
array
Description

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

risk_score__start

Type
string
Description

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

risk_score__end

Type
string
Description

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

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook