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
email	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
unsubscription_reason	string

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

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 -X POST https://api.buttondown.email/v1/subscribers

Parameters

parameter	type	description	optional
email	string
notes	string
metadata	object
tags	array
referrer_url	string
referring_subscriber_id	string
subscriber_type

Responses

Status	Description	Sample Response
201	Created	{ "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	Bad Request	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Status

Description

Sample Response

201

Created

{
    "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

Bad Request

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

403

Forbidden

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

List Subscribers

$ curl -X GET https://api.buttondown.email/v1/subscribers

Parameters

parameter	type	description	optional
type	array
ids	array
email	string
tag	string
-tag	string
ordering	unknown
utm_source	array
price	array

Responses

Status	Description	Sample Response
200	OK	{ "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": "" } ], "count": 1 }
400	Bad Request	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Error codes

type	identifier	description
Invalid tag	invalid_tag

Retrieve Subscriber

$ curl -X GET https://api.buttondown.email/v1/subscribers/{pk}

Responses

Status

Description

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

403

Forbidden

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

404

Not Found

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

Delete Subscriber

$ curl -X DELETE https://api.buttondown.email/v1/subscribers/{pk}

Responses

Status	Description	Sample Response
204	No Content	{}
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Update Subscriber

$ curl -X PATCH https://api.buttondown.email/v1/subscribers/{pk}

Parameters

parameter	type	description	optional
email	string
notes	string
metadata	object
tags	array
referrer_url	string
subscriber_type

Responses

Status	Description	Sample Response
200	OK	{ "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	Bad Request	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Error codes

type	identifier	description
Invalid tag	invalid_tag

Send Reminder

$ curl -X POST https://api.buttondown.email/v1/subscribers/{pk}/send-reminder

Responses

Status	Description	Sample Response
200	OK	{}
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Send Email To

$ curl -X POST https://api.buttondown.email/v1/subscribers/{pk}/emails/{email_pk}

Responses

Status	Description	Sample Response
200	OK	{}
400	Bad Request	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

On this page

Enums

Endpoints

/subscribers/{pk}/send-reminder

/subscribers/{pk}/emails/{email_pk}