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