Buttondown Documentation

Buttondown Documentation

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook

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": "13121cd6-0dfc-424c-bb12-988b0a32fcb3",
    "creation_date": "2020-09-29T00:00:00+00:00",
    "email_address": "telemachus@buttondown.email",
    "notes": "",
    "metadata": {
        "name": "Telemachus"
    },
    "tags": [],
    "referrer_url": "",
    "secondary_id": 1,
    "type": "unactivated",
    "source": "organic",
    "utm_campaign": "",
    "utm_medium": "",
    "utm_source": "",
    "referral_code": "",
    "avatar_url": "",
    "stripe_coupon": null,
    "unsubscription_date": null,
    "churn_date": null,
    "undeliverability_date": null,
    "undeliverability_reason": null,
    "upgrade_date": null,
    "unsubscription_reason": "",
    "transitions": [],
    "ip_address": null,
    "last_open_date": null,
    "last_click_date": null,
    "stripe_customer_id": null,
    "subscriber_import_id": null,
    "risk_score": null,
    "stripe_customer": null
}

Body parameters

All parameters are optional unless explicitly specified.

email_address

Type
string
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

tags

Type
array

referrer_url

Type
string

type

Type
SubscriberType

unsubscription_reason

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.
subscriber_type_invalidThe subscriber type provided is not valid.
tag_invalidThe tag provided is invalid or does not exist.

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook