Buttondown logo

Get started

Routes

IntroductionTypesSourcesUndeliverability reasons

Routes

Listing subscribersRetrieving a subscriberCreating a subscriberUpdating a subscriberDeleting a subscriberSending a reminderSending an emailListing survey responsesSubscriber referralsSending a magic linkSubscriber automationsUpdating a subscriber's automationSubscriber Stripe subscriptions

Buttondown logo

Updating a subscriber

You'll notice that the endpoint is /subscribers/{id_or_email}, not {id}. This is because you can retrieve a subscriber by either their ID or their email address, so you don't have to store or remember the ID if you don't want to.

If you update a subscriber's type from premium to unsubscribed, it will also cancel their backing Stripe subscription.

Sample requests

These sample requests are autogenerated by the OpenAPI spec. This endpoint requires one or more parameters in the URL: those are offset in curly-braces.

import requests

url = "https://api.buttondown.com/v1/subscribers/{id_or_email}"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "email_address": "telemachus@buttondown.email",
  "notes": "One of our first subscribers!"
}

response = requests.request("PATCH", url, headers=headers, json=data)
print(response.text)

Sample responses

The IDs and values referenced in these responses are fake; please only rely on these responses for overall structure.

{
    "id": "sub_0k28edc3fw896bp4mrhc535z5k",
    "creation_date": "2020-09-29T00:00:00+00:00",
    "avatar_url": "",
    "churn_date": null,
    "commenting_disabled": false,
    "email_address": "telemachus@buttondown.email",
    "gift_subscription_message": "",
    "ip_address": null,
    "last_click_date": null,
    "last_open_date": null,
    "delivered_count": null,
    "open_count": null,
    "clicked_count": null,
    "open_rate": null,
    "click_rate": null,
    "metadata": {
        "name": "Telemachus"
    },
    "notes": "",
    "purchased_by": null,
    "purchased_message": null,
    "referral_code": "",
    "referrer_url": "",
    "risk_score": null,
    "secondary_id": 1,
    "source": "organic",
    "stripe_coupon": null,
    "stripe_customer_id": null,
    "subscriber_import_id": null,
    "tags": [],
    "transitions": [],
    "email_transitions": [],
    "form_id": null,
    "firewall_reasons": [],
    "type": "unactivated",
    "undeliverability_date": null,
    "undeliverability_reason": null,
    "unsubscription_date": null,
    "unsubscription_reason": "",
    "upgrade_date": null,
    "utm_campaign": "",
    "utm_medium": "",
    "utm_source": "",
    "stripe_customer": null
}

Body parameters

All parameters are optional unless explicitly specified.

commenting_disabled

Type
boolean
Description

Whether this subscriber is prevented from commenting.

email_address

Type
string
Description

The email address of the subscriber.

Example
"telemachus@buttondown.email"

notes

Type
string
Description

Any notes you want to attach to the subscriber. These are not publicly visible.

Example
"One of our first subscribers!"

metadata

Type
object
Description

A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested — you can store objects and arrays within your metadata. (You can read more about metadata.)

tags

Type
array

referrer_url

Type
string

type

Type
SubscriberType

unsubscription_reason

Type
string

email_which_prompted_unsubscription_id

Type
string

Error codes

This endpoint may return the following error codes. See the error codes reference for more details about error handling.

Error CodeDescription
email_already_existsA subscriber with this email address already exists.
email_has_been_changed_too_many_timesThis subscriber's email has been changed too many times.
email_invalidThe email address provided is not valid.
firewall_blockedThe email address was blocked by the firewall.
subscriber_type_invalidThe subscriber type provided is not valid.
tag_invalidThe tag provided is invalid or does not exist.