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.
Which is why we also present this chart without paid subscriptions_.
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.
Which is why we also present this chart without paid subscriptions_.
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:
subscriber_type and email to type and email_address respectively.external_url in favor of absolute_url.A unique TypeID associated with the object.
The date and time at which the object was first created.
URL of the subscriber's avatar image (e.g. a Gravatar URL), if available.
The date of the subscriber's most recent bounce event. May be set even if the subscriber has not yet been marked as undeliverable.
The reason of the subscriber's most recent bounce event. May be set even if the subscriber has not yet been marked as undeliverable.
Access to the subscriber's email was denied.
The email failed authentication checks (DMARC, SPF, or relay permissions).
The delivery attempt timed out before the email could be delivered.
The subscriber's domain is blocked.
The subscriber's email address is blocked.
The subscriber's email address permanently bounced (the address does not exist or is unreachable).
The subscriber's IP address is blocked.
The subscriber's IP address is undeliverable.
The subscriber's email is malformed.
The subscriber's email is on an ESP denylist.
The subscriber is deemed undeliverable for an unknown reason.
The subscriber's mailbox is out of storage.
The email contained a problematic URL.
The email provider, i.e. Gmail, acknowledges the message, but is temporarily refusing to send the message due to overall volume coming from the sender. Sender can mean a number of different things. For instance, it can mean that your specific newsletter is sending a high amount of volume. It can mean your domain is sending a high amount of volume. Or, in rare cases, it can mean that Buttondown itself as an overall system is sending too much volume. You do not need to change or retry any errors you see due to rate limiting. Buttondown will automatically handle that. However, if you see this error come up often, consider more regularly sending your email at a specific cadence, i.e. weekly.
The email was marked as spam.
The email encountered a temporary delivery issue and will be retried automatically.
The subscriber's email account is disabled.
The subscriber's email does not exist.
SPF validation failed for the email.
The subscriber's email is unreachable.
When the subscriber cancelled their paid subscription, if applicable.
Whether this subscriber is prevented from commenting.
The ISO 3166-1 alpha-2 country code inferred from the subscriber's IP address at signup, if available.
The email address of the subscriber.
When the subscriber's gift subscription expires, if applicable.
A custom message that was sent to the subscriber when the gift subscription was created.
The IP address recorded when the subscriber signed up, if available.
When the subscriber most recently clicked a link in an email.
When the subscriber most recently opened an email.
The number of distinct emails — both broadcasts and automation sends — delivered to this subscriber. Cached and refreshed periodically, so it may lag recent activity.
The subscriber's open count.
The subscriber's clicked count.
The subscriber's open rate, computed from engagement counts. Null if delivered_count is 0 or null.
The subscriber's click rate, computed from engagement counts. Null if delivered_count is 0 or null.
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.)
Any notes you want to attach to the subscriber. These are not publicly visible.
The email address of the individual who purchased this subscription on behalf of the subscriber.
A custom message that was sent to the subscriber when the subscription was purchased on behalf of the subscriber.
The subscriber's unique referral code, used to attribute referred signups.
The URL the subscriber was referred from (e.g. where they submitted the subscription form).
The risk score of the subscriber. Positive numbers represent a higher risk; negative numbers represent a lower risk.
A human-readable sequential identifier, unique within the newsletter.
Where the subscriber signed up from (e.g. api, import, form).
This subscriber was added by a member of Buttondown support staff.
Subscriber created by API.
This subscriber joined via Carrd.
This subscriber joined via commenting on an email.
This subscriber subscribed via an embedded form.
This subscriber subscribed via a Buttondown form.
This subscriber was imported from another service.
This subscriber joined via Memberful.
This subscriber joined via Netlify.
This subscriber subscribed to your newsletter of their own volition.
This subscriber joined via Patreon.
This subscriber joined via Shopify.
This subscriber joined via Stripe.
This subscriber was added by a user with write permissions for subscribers within the Buttondown dashboard.
This subscriber joined via Zapier.
The Stripe coupon applied to the subscriber's paid subscription, if any.
The Stripe customer ID associated with the subscriber, if any.
The ID of the subscriber import that created this subscriber, if any.
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).
The history of subscriber type transitions (e.g. regular → premium).
The history of email address changes for this subscriber.
The ID of the registration form the subscriber signed up through, if any.
Information collected by Buttondown's firewall about this subscriber. See the firewall for more information.
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.
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.
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.
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.
Subscribers which were previously premium subscribers, but have since churned but are not unsubscribed. These subscribers receive public emails as well as teasers.
Subscribers that have been gifted free premium subscriptions.
Subscribers who have not yet confirmed their email or opted in.
Subscribers who have not yet purchased a subscription to your newsletter. Subscribers will only be marked as unpaid if you have turned off free subscriptions to your paid newsletter; otherwise, they will be marked as Regular.
Buttondown marks subscribers as undeliverable when we receive some sort of proof that this address does not exist, such as a suppression notification from one of our email providers or a hard bounce from the host or mailbox itself. We don't try to deliver email to subscribers marked as undeliverable, but you can, in some cases, change their email address (e.g. if they've changed their email address in your CRM, or if you had a typo in their email address) to try and fix things.
Subscribers who technically have active paid subscriptions, but have not paid their invoices in time.
Subscribers that are on a temporary hold from their premium subscription, but are still subscribed to your newsletter.
Normal subscribers who have not unsubscribed or deactivated in any way.
Subscribers that you have banned from your newsletter. This is not the same as unsubscribed: those subscribers removed themselves.
Subscribers that are temporarily receiving a premium subscription to your newsletter.
Subscribers that have or have been unsubscribed from your newsletter.
Subscribers who have a premium subscription starting in the future.
When the subscriber was marked as undeliverable, if applicable.
The reason the subscriber is undeliverable. (Only populated for undeliverable subscribers.)
Access to the subscriber's email was denied.
The email failed authentication checks (DMARC, SPF, or relay permissions).
The delivery attempt timed out before the email could be delivered.
The subscriber's domain is blocked.
The subscriber's email address is blocked.
The subscriber's email address permanently bounced (the address does not exist or is unreachable).
The subscriber's IP address is blocked.
The subscriber's IP address is undeliverable.
The subscriber's email is malformed.
The subscriber's email is on an ESP denylist.
The subscriber is deemed undeliverable for an unknown reason.
The subscriber's mailbox is out of storage.
The email contained a problematic URL.
The email provider, i.e. Gmail, acknowledges the message, but is temporarily refusing to send the message due to overall volume coming from the sender. Sender can mean a number of different things. For instance, it can mean that your specific newsletter is sending a high amount of volume. It can mean your domain is sending a high amount of volume. Or, in rare cases, it can mean that Buttondown itself as an overall system is sending too much volume. You do not need to change or retry any errors you see due to rate limiting. Buttondown will automatically handle that. However, if you see this error come up often, consider more regularly sending your email at a specific cadence, i.e. weekly.
The email was marked as spam.
The email encountered a temporary delivery issue and will be retried automatically.
The subscriber's email account is disabled.
The subscriber's email does not exist.
SPF validation failed for the email.
The subscriber's email is unreachable.
When the subscriber unsubscribed, if applicable.
Free-text reason the subscriber unsubscribed, if provided.
When the subscriber upgraded to a paid subscription, if applicable.
The UTM campaign the subscriber was attributed to at signup.
The UTM medium the subscriber was attributed to at signup.
The UTM source the subscriber was attributed to at signup.
If expanded, the Stripe customer associated with this subscriber.
If expanded, the Stripe subscription backing this subscriber's paid subscription.