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 | |
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 | optional |
---|---|---|---|
type | string |
| |
tag | string | An optional filter allowing you to filter subscribers based on a given tag. Provide the ID of the tag, not the name. | |
string | An optional filter allowing you to filter subscribers based on a substring. Providing a value of | ||
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 | description |
---|---|
regular | normal subscribers who have not unsubscribed or deactivated in any way |
removed | subscribers who have been explicitly removed by the newsletter (notably, this does not mean unsubscribers: use /v1/unsubscribers for that!) |
unactivated | subscribers who have not yet confirmed their email or opted in |
unpaid | subscribers who have not yet purchased a subscription to your newsletter |
premium | subscribers with active premium subscriptions |
gifted | subscribers that have been gifted free premium subscriptions |
unsubscribed | subscribers that have voluntarily unsubscribed from your newsletter |
spammy | subscribers that have been deemed spammy by Buttondown's automated systems |
trialed | subscribers that are temporarily receiving a premium subscription to your newsletter |
paused | subscribers that are on a temporary hold from their premium subscription, but are still subscribed to your newsletter |
Responses
Status | Description | Sample Response |
---|---|---|
200 |
|
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 |
---|---|---|---|
string | |||
metadata | map | ||
notes | map | ||
referrer_url | string | ||
tags | array<string> | array<uuid> |
Responses
Status | Description | Sample Response |
---|---|---|
201 |
| |
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 |
---|---|---|---|
string | |||
metadata | map | ||
notes | map | ||
referrer_url | string | ||
tags | array<string> | array<uuid> |
Responses
Status | Description | Sample Response |
---|---|---|
200 |
|
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 |
|
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 |
|