Subscriber
Subscribers are the main way you collect email addresses and recipients on Buttondown. They're what you see on your subscribers page.
Basic subscriber
{"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 |
---|---|---|
id | string | |
string | ||
notes | string | |
metadata | object | |
tags | array | |
referrer_url | string | |
creation_date | string | |
secondary_id | integer | |
subscriber_type | SubscriberType | |
source | SubscriberSource | |
utm_campaign | string | |
utm_medium | string | |
utm_source | string | |
referral_code | string | |
avatar_url | string | |
stripe_customer_id | string | |
unsubscription_date | string | |
churn_date | string | |
unsubscription_reason | string | |
transitions | array |
Type (SubscriberType)
Represents the state of a subscriber and what emails they should or should not be receiving. This type is meant to be fully expressive so as to consolidate the logic of determining what emails a subscriber should receive into a single place.
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 |
complained | complained | subscribers that have registered a complaint with their email provider |
malformed | malformed | subscribers whose email appears to be invalid |
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 |
churned | churned | subscribers which were previously premium subscribers, but have since churned but are not unsubscribed |
Source (SubscriberSource)
Represents the original provenance of a subscriber. This value is not exposed to subscribers; it's only used for internal tracking purposes and governs some of the behavior of the subscriber (i.e. whether or not to require double opt-in.)
type | identifier | description |
---|---|---|
API | api | |
import | import | |
organic | organic | |
admin | admin | |
user | user |
Create Subscriber
curl
python
ruby
typescript
Copy to clipboard
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/subscribers"response = requests.post(f"{BASE_URL}{ENDPOINT}", headers=headers)
Parameters
parameter | type | description | optional |
---|---|---|---|
string | |||
notes | string | ||
metadata | object | ||
tags | array | ||
referrer_url | string | ||
utm_campaign | string | ||
utm_medium | string | ||
utm_source | string | ||
referring_subscriber_id | string | ||
subscriber_type |
Responses
Status | Description | Sample Response |
---|---|---|
201 | Created |
|
400 | Bad Request |
|
403 | Forbidden |
|
Error codes
type | identifier | description |
---|---|---|
Email already exists | email_already_exists | A subscriber already exists with that email |
Email invalid | email_invalid | The email is invalid |
Tag invalid | tag_invalid | The tag is invalid |
List Subscribers
curl
python
ruby
typescript
Copy to clipboard
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/subscribers"response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)
Parameters
parameter | type | description | optional |
---|---|---|---|
type | array | ||
ids | array | ||
date | array | ||
string | |||
tag | string | ||
-tag | string | ||
ordering | string | ||
utm_source | array | ||
price | array |
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
400 | Bad Request |
|
403 | Forbidden |
|
404 | Not Found |
|
Error codes
type | identifier | description |
---|---|---|
Invalid tag | invalid_tag |
Retrieve Subscriber
curl
python
ruby
typescript
Copy to clipboard
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/subscribers/{pk_or_email}"response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
403 | Forbidden |
|
404 | Not Found |
|
Delete Subscriber
curl
python
ruby
typescript
Copy to clipboard
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/subscribers/{pk_or_email}"response = requests.delete(f"{BASE_URL}{ENDPOINT}", headers=headers)
Responses
Status | Description | Sample Response |
---|---|---|
204 | No Content |
|
403 | Forbidden |
|
404 | Not Found |
|
Update Subscriber
curl
python
ruby
typescript
Copy to clipboard
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/subscribers/{pk_or_email}"response = requests.patch(f"{BASE_URL}{ENDPOINT}", headers=headers)
Parameters
parameter | type | description | optional |
---|---|---|---|
string | |||
notes | string | ||
metadata | object | ||
tags | array | ||
referrer_url | string | ||
subscriber_type | |||
unsubscription_reason | string |
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
400 | Bad Request |
|
403 | Forbidden |
|
404 | Not Found |
|
Error codes
type | identifier | description |
---|---|---|
Invalid tag | invalid_tag |
Send Reminder
curl
python
ruby
typescript
Copy to clipboard
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/subscribers/{pk_or_email}/send-reminder"response = requests.post(f"{BASE_URL}{ENDPOINT}", headers=headers)
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
403 | Forbidden |
|
Send Email To
curl
python
ruby
typescript
Copy to clipboard
import requestsheaders = {"Authorization": f"Token {BUTTONDOWN_API_KEY}",}BASE_URL = "https://api.buttondown.email"ENDPOINT = "/v1/subscribers/{pk_or_email}/emails/{email_pk}"response = requests.post(f"{BASE_URL}{ENDPOINT}", headers=headers)
Responses
Status | Description | Sample Response |
---|---|---|
200 | OK |
|
400 | Bad Request |
|
403 | Forbidden |
|
404 | Not Found |
|