Buttondown logo

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.
{
    "avatar_url": "",
    "churn_date": null,
    "creation_date": "2020-09-29T00:00:00+00:00",
    "email_address": "telemachus@buttondown.email",
    "email_transitions": [],
    "gift_subscription_message": "",
    "id": "13121cd6-0dfc-424c-bb12-988b0a32fcb3",
    "ip_address": null,
    "last_click_date": null,
    "last_open_date": 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": null,
    "stripe_customer_id": null,
    "subscriber_import_id": null,
    "tags": [],
    "transitions": [],
    "type": "unactivated",
    "undeliverability_date": null,
    "undeliverability_reason": null,
    "unsubscription_date": null,
    "unsubscription_reason": "",
    "upgrade_date": null,
    "utm_campaign": "",
    "utm_medium": "",
    "utm_source": ""
}

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.

avatar_url

Type
string

churn_date

Type
string

email_address

Type
string
Description

The email address of the subscriber.

gift_subscription_message

Type
string
Description

A custom message that was sent to the subscriber when the gift subscription was created.

ip_address

Type
string

last_click_date

Type
string

last_open_date

Type
string

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.)

notes

Type
string
Description

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

purchased_by

Type
string
Description

The email address of the individual who purchased this subscription on behalf of the subscriber.

purchased_message

Type
string
Description

A custom message that was sent to the subscriber when the subscription was purchased on behalf of the subscriber.

referral_code

Type
string

referrer_url

Type
string

risk_score

Type
number
Description

The risk score of the subscriber. Positive numbers represent a higher risk; negative numbers represent a lower risk.

secondary_id

Type
integer

source

Type
SubscriberSource

stripe_coupon

Type
StripeCoupon

stripe_customer_id

Type
string

subscriber_import_id

Type
string

tags

Type
array

transitions

Type
array

email_transitions

Type
array

type

Type
SubscriberType

undeliverability_date

Type
string

undeliverability_reason

Type
SubscriberUndeliverabilityReason
Description

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

unsubscription_date

Type
string

unsubscription_reason

Type
string

upgrade_date

Type
string

utm_campaign

Type
string

utm_medium

Type
string

utm_source

Type
string

stripe_customer

Type
object
Buttondown logo

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.
{
    "avatar_url": "",
    "churn_date": null,
    "creation_date": "2020-09-29T00:00:00+00:00",
    "email_address": "telemachus@buttondown.email",
    "email_transitions": [],
    "gift_subscription_message": "",
    "id": "13121cd6-0dfc-424c-bb12-988b0a32fcb3",
    "ip_address": null,
    "last_click_date": null,
    "last_open_date": 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": null,
    "stripe_customer_id": null,
    "subscriber_import_id": null,
    "tags": [],
    "transitions": [],
    "type": "unactivated",
    "undeliverability_date": null,
    "undeliverability_reason": null,
    "unsubscription_date": null,
    "unsubscription_reason": "",
    "upgrade_date": null,
    "utm_campaign": "",
    "utm_medium": "",
    "utm_source": ""
}

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.

avatar_url

Type
string

churn_date

Type
string

email_address

Type
string
Description

The email address of the subscriber.

gift_subscription_message

Type
string
Description

A custom message that was sent to the subscriber when the gift subscription was created.

ip_address

Type
string

last_click_date

Type
string

last_open_date

Type
string

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.)

notes

Type
string
Description

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

purchased_by

Type
string
Description

The email address of the individual who purchased this subscription on behalf of the subscriber.

purchased_message

Type
string
Description

A custom message that was sent to the subscriber when the subscription was purchased on behalf of the subscriber.

referral_code

Type
string

referrer_url

Type
string

risk_score

Type
number
Description

The risk score of the subscriber. Positive numbers represent a higher risk; negative numbers represent a lower risk.

secondary_id

Type
integer

source

Type
SubscriberSource

stripe_coupon

Type
StripeCoupon

stripe_customer_id

Type
string

subscriber_import_id

Type
string

tags

Type
array

transitions

Type
array

email_transitions

Type
array

type

Type
SubscriberType

undeliverability_date

Type
string

undeliverability_reason

Type
SubscriberUndeliverabilityReason
Description

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

unsubscription_date

Type
string

unsubscription_reason

Type
string

upgrade_date

Type
string

utm_campaign

Type
string

utm_medium

Type
string

utm_source

Type
string

stripe_customer

Type
object