Subscribers

Subscribers are the main way you collect email addresses and recipients on Buttondown. They're what you see on your subscribers page.

The subscriber object

A subscriber looks like this:

{
    "creation_date": "2019-08-24T14:15:22Z",
    "email": "user@example.com",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "metadata": {
        "foo": "bar"
    },
    "notes": "",
    "referrer_url": "http://jmduke.com",
    "secondary_id": 3,
    "source": "api",
    "subscriber_type": "regular",
    "tags": [],
    "utm_campaign": "",
    "utm_medium": "",
    "utm_source": ""
}

field	type	description
creation_date	datetime
email	string
id	uuid
metadata	map
notes	string
referrer_url	url
secondary_id	int
subscriber_type	SubscriberType
source	string
tags	array<uuid>
utm_campaign	string
utm_medium	string
utm_source	string

Listing subscribers

GET → https://api.buttondown.email/v1/subscribers

Parameters

parameter	type	description
type	string	`An optional filter to allow you to only retrieve a subset of subscribers. The API accepts the values listed below.`
tag	string	An optional filter allowing you to filter subscribers based on a given tag. Provide the ID of the tag, not the name.
email	string	An optional filter allowing you to filter subscribers based on a substring. Providing a value of `doe` would match both `jane.doe@gmail.com` and `john.doe@gmail.com`, but not `jane.dooe@gmail.com`.
page	string	A page number within the paginated result set. Each page has 100 results.
ordering	string	Which field to use when ordering the results.

Subscriber types

type	identifier	description
regular	regular	normal subscribers who have not unsubscribed or deactivated in any way
premium	premium	subscribers with active premium subscriptions
trialed	trialed	subscribers that are temporarily receiving a premium subscription to your newsletter
unpaid	unpaid	subscribers who have not yet purchased a subscription to your newsletter
gifted	gifted	subscribers that have been gifted free premium subscriptions
churning	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
unactivated	unactivated	subscribers who have not yet confirmed their email or opted in
paused	paused	subscribers that are on a temporary hold from their premium subscription, but are still subscribed to your newsletter
unsubscribed	unsubscribed	subscribers that have voluntarily unsubscribed from your newsletter
spammy	spammy	subscribers that have been deemed spammy by Buttondown's automated systems
removed	removed	subscribers who have been explicitly removed by the newsletter (notably, this does not mean unsubscribers: use /v1/unsubscribers for that!)
Past due	past_due	subscribers who technically have active paid subscriptions, but have not paid their invoices in time

Responses

Status	Description	Sample Response
200		{ "count": 1, "next": "foo", "previous": null, "results": [ { "creation_date": "2019-08-24T14:15:22Z", "email": "user@example.com", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "metadata": { "foo": "bar" }, "notes": "", "referrer_url": "http://jmduke.com", "secondary_id": 3, "source": "api", "subscriber_type": "regular", "tags": [], "utm_campaign": "", "utm_medium": "", "utm_source": "" } ] }

Status

Description

Sample Response

200

{
    "count": 1,
    "next": "foo",
    "previous": null,
    "results": [
        {
            "creation_date": "2019-08-24T14:15:22Z",
            "email": "user@example.com",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "metadata": {
                "foo": "bar"
            },
            "notes": "",
            "referrer_url": "http://jmduke.com",
            "secondary_id": 3,
            "source": "api",
            "subscriber_type": "regular",
            "tags": [],
            "utm_campaign": "",
            "utm_medium": "",
            "utm_source": ""
        }
    ]
}

Creating a new subscriber

POST → https://api.buttondown.email/v1/subscribers

If Buttondown cannot create a new subscriber with the email address you've provided, there are a few likely reasons why. They're enumerated below:

A subscriber with that email has already been unsubscribed.
That email address (justin@gmail.com) is already subscribed.
That email address (justin@gmail.com) is already subscribed, but has not confirmed their email.
That email address (justin@gmail.com) is already subscribed, but has not provided payment.

Parameters

parameter	type	description	optional
email	string
metadata	map
notes	map
referrer_url	string
tags	array<string> \| array<uuid>

Responses

Status	Description	Sample Response
201		{ "creation_date": "2019-08-24T14:15:22Z", "email": "user@example.com", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "metadata": { "foo": "bar" }, "notes": "", "referrer_url": "http://jmduke.com", "secondary_id": 3, "source": "api", "subscriber_type": "regular", "tags": [], "utm_campaign": "", "utm_medium": "", "utm_source": "" }
400	If the email is invalid for any reason or if the subscriber already exists in our system.	{}

Status

Description

Sample Response

201

{
    "creation_date": "2019-08-24T14:15:22Z",
    "email": "user@example.com",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "metadata": {
        "foo": "bar"
    },
    "notes": "",
    "referrer_url": "http://jmduke.com",
    "secondary_id": 3,
    "source": "api",
    "subscriber_type": "regular",
    "tags": [],
    "utm_campaign": "",
    "utm_medium": "",
    "utm_source": ""
}

400

If the email is invalid for any reason or if the subscriber already exists in our system.

{}

Updating a subscriber

PATCH → https://api.buttondown.email/v1/subscribers/<id>

Parameters

parameter	type	description	optional
email	string
metadata	map
notes	map
referrer_url	string
tags	array<string> \| array<uuid>

Responses

Status	Description	Sample Response
200		{ "creation_date": "2019-08-24T14:15:22Z", "email": "user@example.com", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "metadata": { "foo": "bar" }, "notes": "", "referrer_url": "http://jmduke.com", "secondary_id": 3, "source": "api", "subscriber_type": "regular", "tags": [], "utm_campaign": "", "utm_medium": "", "utm_source": "" }

Status

Description

Sample Response

200

{
    "creation_date": "2019-08-24T14:15:22Z",
    "email": "user@example.com",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "metadata": {
        "foo": "bar"
    },
    "notes": "",
    "referrer_url": "http://jmduke.com",
    "secondary_id": 3,
    "source": "api",
    "subscriber_type": "regular",
    "tags": [],
    "utm_campaign": "",
    "utm_medium": "",
    "utm_source": ""
}

Deleting a subscriber

DELETE → https://api.buttondown.email/v1/subscribers/<id>

Responses

Status	Description	Sample Response
204		{}

Retrieving a specific subscriber

GET → https://api.buttondown.email/v1/subscribers/<id>

Responses

Status	Description	Sample Response
200		{ "creation_date": "2019-08-24T14:15:22Z", "email": "user@example.com", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "metadata": { "foo": "bar" }, "notes": "", "referrer_url": "http://jmduke.com", "secondary_id": 3, "source": "api", "subscriber_type": "regular", "tags": [], "utm_campaign": "", "utm_medium": "", "utm_source": "" }

Status

Description

Sample Response

200

{
    "creation_date": "2019-08-24T14:15:22Z",
    "email": "user@example.com",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "metadata": {
        "foo": "bar"
    },
    "notes": "",
    "referrer_url": "http://jmduke.com",
    "secondary_id": 3,
    "source": "api",
    "subscriber_type": "regular",
    "tags": [],
    "utm_campaign": "",
    "utm_medium": "",
    "utm_source": ""
}

Sending an email to a specific subscriber

POST → https://api.buttondown.email/v1/subscribers/<id>/emails/<email_id>

Responses

Status	Description	Sample Response
200		{}

Sending a reminder to a specific subscriber to confirm their email address

POST → https://api.buttondown.email/v1/subscribers/<id>/send-reminder

Responses

Status	Description	Sample Response
200		{}
400	Returned if the subscriber has already confirmed their email address	{}

On this page

The subscriber object

Listing subscribers

Subscriber types

Creating a new subscriber

Updating a subscriber

Deleting a subscriber

Retrieving a specific subscriber

Sending an email to a specific subscriber

Sending a reminder to a specific subscriber to confirm their email address