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.
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

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