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.

Resubscribing an unsubscribed subscriber

  • {"type": "regular"} reactivates them immediately, with no confirmation email.
  • {"type": "unactivated"} moves them back to pending and sends a new confirmation email, so they only receive emails again once they've confirmed. This is only available for unsubscribed subscribers.

Note that {"type": "unsubscribed"} only applies to subscribers who are actively subscribed. Someone who is still unactivated, or already in a terminal state like undeliverable, can't be unsubscribed; delete them instead. These requests return a 400 with the code subscriber_type_invalid.

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": "",
    "bounce_date": null,
    "bounce_reason": null,
    "churn_date": null,
    "commenting_disabled": false,
    "country": null,
    "email_address": "telemachus@buttondown.email",
    "gift_subscription_end_date": null,
    "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,
    "stripe_subscription": 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
Description

A list of tag names applied to the subscriber. Tags that don't already exist will be created, which requires a plan that includes tags (Basic or higher).

referrer_url

Type
string
Description

The URL the subscriber was referred from (e.g. where they submitted the subscription form).

type

Type
SubscriberType
Description

The subscriber's lifecycle state. One of: blocked (blocked by the newsletter), churned (previously paid, subscription ended), churning (paying but won't renew), complained (marked an email as spam), gifted (granted free premium access by the newsletter), past_due (paid subscription with an overdue invoice), paused (premium subscription paused), premium (paying subscriber), regular (active free subscriber), removed (removed by the newsletter), trialed (temporarily enrolled in premium), unactivated (pending double opt-in confirmation), undeliverable (determined undeliverable), unpaid (has not paid yet), unsubscribed (voluntarily unsubscribed), upcoming (paid subscription that has not started yet). Subscribers with premium, gifted, trialed, or churning have access to premium content; use these to distinguish paid from free subscribers.

unsubscription_reason

Type
string
Description

Free-text reason the subscriber unsubscribed, if provided.

email_which_prompted_unsubscription_id

Type
string
Description

The ID of the email that prompted the subscriber to unsubscribe, if any.