Buttondown Documentation

Buttondown Documentation

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook

Subscriber types

As you'll see, most of the logic here is really to deal with the state space of paid subscriptions, and therefore might not be super relevant to you.

flowchart
    unactivated[Unactivated] --> regular[Regular]
    unactivated --> unpaid[Unpaid]
    unpaid --> premium
    regular --> premium[Premium]
    trialed --> premium
    trialed --> regular
    trialed --> unpaid
    unactivated --> trialed[Trialed]
    regular --> gifted[Gifted]
    premium --> churning[Churning]
    premium --> paused[Paused]
    regular --> unsubscribed[Unsubscribed]
    regular --> spammy[Spammy]
    regular --> undeliverable[Undeliverable]
    regular --> complained[Complained]
    premium --> past_due[Past due]
    past_due --> churned
    past_due --> premium
    churning --> churned[Churned]
    regular --> disabled[Disabled]
    paused --> premium
    churned --> premium

    subgraph paid_subscriptions
      premium
      trialed
      gifted
      unpaid
      churning
      past_due
      paused
      churned
    end

    subgraph terminal['']
      complained
      spammy
      undeliverable
      disabled
    end

Which is why we also present this chart without paid subscriptions_.

flowchart
    unactivated[Unactivated] --> regular[Regular]
    unactivated --> unpaid[Unpaid]
    regular --> unsubscribed[Unsubscribed]
    regular --> spammy[Spammy]
    regular --> undeliverable[Undeliverable]
    regular --> complained[Complained]

    subgraph terminal['']
      complained
      spammy
      undeliverable
      disabled[Disabled]
    end

Represents the state of a subscriber and what emails they should or should not be receiving. This type is meant to be fully expressive so as to consolidate the logic of determining what emails a subscriber should receive into a single place.

Note that the only types that can be set programmatically are REGULAR, UNSUBSCRIBED, GIFTED and UNPAID. All other types are meant to be user-visible and cannot be set programmatically.

Regular

Type
regular
Description
Normal subscribers who have not unsubscribed or deactivated in any way.

Premium

Type
premium
Description
Subscribers with active premium subscriptions.

Blocked

Type
blocked
Description
Subscribers that were automatically blocked from signing up for your newsletter by Buttondown's automated filtering systems. You can review the subscriber's email address and make a decision about whether to allow them to subscribe.

Trialed

Type
trialed
Description
Subscribers that are temporarily receiving a premium subscription to your newsletter.

Unpaid

Type
unpaid
Description
Subscribers who have not yet purchased a subscription to your newsletter.

Gifted

Type
gifted
Description
Subscribers that have been gifted free premium subscriptions.

Churning

Type
churning
Description
Subscribers who have elected to not renew their subscription to your newsletter and will become unpaid subscribers at the end of their current billing period.

Unactivated

Type
unactivated
Description
Subscribers who have not yet confirmed their email or opted in.

Paused

Type
paused
Description
Subscribers that are on a temporary hold from their premium subscription, but are still subscribed to your newsletter.

Unsubscribed

Type
unsubscribed
Description
Subscribers that have or have been unsubscribed from your newsletter.

Spammy

Type
spammy
Description
Subscribers that have been deemed spammy by Buttondown's automated systems.

Undeliverable

Type
undeliverable
Description
Subscribers who have been unable to receive their email.

Complained

Type
complained
Description
Subscribers that have registered a complaint with their email provider. Buttondown will not try to send them any future emails; no action is required on your part.

Malformed

Type
malformed
Description
Subscribers whose email appears to be invalid.

Removed

Type
removed
Description
Subscribers who have been explicitly removed by the newsletter (notably, this does not mean unsubscribers: use /v1/unsubscribers for that!)

Disabled

Type
disabled
Description
Subscribers who have been disabled by the newsletter.

Disposable

Type
disposable
Description
Subscribers who have been deemed disposable by Buttondown's automated systems.

Past due

Type
past_due
Description
Subscribers who technically have active paid subscriptions, but have not paid their invoices in time.

Churned

Type
churned
Description
Subscribers which were previously premium subscribers, but have since churned but are not unsubscribed.

Referenced by

Creating a subscriberTypes of automation filtersCustomizing your subscriber dashboardCFBLHow to send a teaser email

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook