Log in or sign up for an account

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.
tagstringAn optional filter allowing you to filter subscribers based on a given tag. Provide the ID of the tag, not the name.
emailstringAn 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`.
pagestringA page number within the paginated result set.
orderingstringWhich field to use when ordering the results.

Subscriber types

typedescription
regularnormal subscribers who have not unsubscribed or deactivated in any way
removedsubscribers who have been explicitly removed by the newsletter (notably, this does not mean unsubscribers: use /v1/unsubscribers for that!)
unactivatedsubscribers who have not yet confirmed their email or opted in
unpaidsubscribers who have not yet purchased a subscription to your newsletter
premiumsubscribers with active premium subscriptions
giftedsubscriebers that have been gifted free premium subscriptions
unsubscribedsubscribers that have voluntarily unsubscribed from your newsletter
spammysubscribers that have been deemed spammy by Buttondown's automated systems
trialedsubscribers that are temporarily receiving a premium subscription to your newsletter
pausedsubscribers that are on a temporary hold from their premium subscription, but are still subscribed to your newsletter

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

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

info

This endpoint is currently in closed beta! If you are interested in using it, email me and I will get you situated.


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

Responses

StatusDescriptionSample Response
200
{}