Buttondown logo

IntroductionTypesSourcesUndeliverability reasons

Routes

Listing subscribersRetrieving a subscriberCreating a subscriberUpdating a subscriberDeleting a subscriberSending a reminderSending an emailListing survey responsesSubscriber referralsSending a magic linkSubscriber automationsUpdating a subscriber's automationSubscriber Stripe subscriptions

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": "13121cd6-0dfc-424c-bb12-988b0a32fcb3",
            "creation_date": "2020-09-29T00:00:00+00:00",
            "avatar_url": "",
            "churn_date": null,
            "email_address": "telemachus@buttondown.email",
            "gift_subscription_message": "",
            "ip_address": null,
            "last_click_date": null,
            "last_open_date": 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": [],
            "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 with the given churn date(s).

churn_date__start

Type
string
Description

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

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

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 with the given last click date(s).

last_click_date__start

Type
string
Description

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

last_open_date__end

Type
string
Description

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

last_open_date__start

Type
string
Description

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

-domain

Type
array
Description

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

-tag

Type
string

-type

Type
SubscriberType[]
Description

If provided, only return subscribers without the given type.

ordering

Type
string

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.

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

type

Type
SubscriberType[]
Description

If provided, only return subscribers with the given type.

undeliverability_date__end

Type
string
Description

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

undeliverability_date__start

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_date__end

Type
string
Description

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

unsubscription_date__start

Type
string
Description

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

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 with the given upgrade date(s).

upgrade_date__start

Type
string
Description

If provided, only return subscribers with the given upgrade date(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).

utm_source

Type
array
Description

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

Error codes

This endpoint may return the following error codes. See the error codes reference for more details about error handling.

Error CodeDescription
date_invalidThe date provided is not valid or is in an incorrect format.
invalid_orderingThe ordering provided is not valid.
invalid_tagThe tag provided is invalid or does not exist.