Buttondown logo

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": "sub_0k28edc3fw896bp4mrhc535z5k",
            "creation_date": "2020-09-29T00:00:00+00:00",
            "avatar_url": "",
            "churn_date": null,
            "commenting_disabled": false,
            "email_address": "telemachus@buttondown.email",
            "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
        }
    ],
    "count": 1
}

Path parameters

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

churn_date__end

Type
string
Description

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

churn_date__start

Type
string
Description

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

coupon

Type
array
Description

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

current_price

Type
array
Description

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

date__end

Type
string
Description

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

date__start

Type
string
Description

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

domain

Type
array
Description

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

email_address

Type
string
Description

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

expand

Type
array
Description

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

form

Type
array
Description

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

ids

Type
array
Description

If provided, only return subscribers with the given IDs.

ip_address

Type
array
Description

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

last_click_date__end

Type
string
Description

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

last_click_date__start

Type
string
Description

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

last_open_date__end

Type
string
Description

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

last_open_date__start

Type
string
Description

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

-domain

Type
array
Description

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

-tag

Type
string
Description

If provided, only return subscribers without the given tag.

-type

Type
SubscriberType[]
Description

If provided, only return subscribers without the given type.

ordering

Type
string
Description

The ordering to apply to the results.

price

Type
array
Description

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

referral_code

Type
array
Description

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

referrer_url

Type
array
Description

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

open_rate__end

Type
string
Description

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

open_rate__start

Type
string
Description

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

click_rate__end

Type
string
Description

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

click_rate__start

Type
string
Description

If provided, only return subscribers with a click rate 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.

risk_score__start

Type
string
Description

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

source

Type
SubscriberSource[]
Description

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

subscriber_import

Type
array
Description

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

tag

Type
array
Description

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

type

Type
SubscriberType[]
Description

If provided, only return subscribers with the given type.

undeliverability_date__end

Type
string
Description

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

undeliverability_date__start

Type
string
Description

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

undeliverability_reason

Type
SubscriberUndeliverabilityReason[]
Description

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

unsubscription_date__end

Type
string
Description

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

unsubscription_date__start

Type
string
Description

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

unsubscription_reason

Type
array
Description

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

upgrade_date__end

Type
string
Description

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

upgrade_date__start

Type
string
Description

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

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

utm_source

Type
array
Description

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