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": ""
}

fieldtypedescription
creation_datedatetime
emailstring
iduuid
metadatamap
notesstring
referrer_urlurl
secondary_idint
subscriber_typeSubscriberType
sourcestring
tagsarray<uuid>
utm_campaignstring
utm_mediumstring
utm_sourcestring

Listing subscribers

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

Parameters

parametertypedescriptionoptional
typestring
  An optional filter to allow you to only retrieve a subset of subscribers. The API accepts the values listed below.
tagstring

An optional filter allowing you to filter subscribers based on a given tag. Provide the ID of the tag, not the name.

emailstring

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.

pagestring

A page number within the paginated result set. Each page has 100 results.

orderingstring

Which field to use when ordering the results.

Subscriber types

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

Responses

StatusDescriptionSample 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

parametertypedescriptionoptional
emailstring
metadatamap
notesmap
referrer_urlstring
tagsarray<string> | array<uuid>

Responses

StatusDescriptionSample 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": ""
}
400If 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

parametertypedescriptionoptional
emailstring
metadatamap
notesmap
referrer_urlstring
tagsarray<string> | array<uuid>

Responses

StatusDescriptionSample 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

StatusDescriptionSample Response
204
{}

Retrieving a specific subscriber

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

Responses

StatusDescriptionSample 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

StatusDescriptionSample 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

StatusDescriptionSample Response
200
{}
400Returned if the subscriber has already confirmed their email address
{}