Buttondown Documentation

Buttondown Documentation

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook

Introduction

Subscribers are the main way you collect email addresses and recipients on Buttondown. They're what you see on your subscribers page.

Relevant changes to the schema:

  • 2024-08-01: renamed subscriber_type and email to type and email_address respectively.
  • 2024-07-13: removed external_url in favor of absolute_url.
{
    "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,
    "stripe_customer": null
}

Fields

id

Type
string
Description
A unique UUID associated with the object.

creation_date

Type
string
Description
The date and time at which the object was created.

email_address

Type
string
Description
The email address of the subscriber.

notes

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

metadata

Type
object
Description
A structured key-value blob that you can use to store arbitrary data on the object.

tags

Type
array

referrer_url

Type
string

secondary_id

Type
integer

type

Type
SubscriberType

source

Type
SubscriberSource

utm_campaign

Type
string

utm_medium

Type
string

utm_source

Type
string

referral_code

Type
string

avatar_url

Type
string

stripe_coupon

Type
StripeCoupon

unsubscription_date

Type
string

churn_date

Type
string

undeliverability_date

Type
string

undeliverability_reason

Type
SubscriberUndeliverabilityReason
Description
The reason the subscriber is undeliverable. (Only populated for undeliverable subscribers.)

upgrade_date

Type
string

unsubscription_reason

Type
string

transitions

Type
array

ip_address

Type
string

last_open_date

Type
string

last_click_date

Type
string

stripe_customer_id

Type
string

subscriber_import_id

Type
string

stripe_customer

Type
object

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook
Log inSign up  ↗