Create Subscriber
Create a new subscriber
Headers
An enumeration.
The behavior to apply when a subscriber with the same email address already exists. Defaults to "no_op", which will return a 400 error if a subscriber with the same email address already exists. Other values include:
- "overwrite", which will overwrite the existing subscriber's data with the new one.
- "add", which will add the new subscriber data to the existing one.
Bypass the firewall for this subscriber creation. Subject to aggressive rate limiting (5 per hour per newsletter).
Bypass the firewall for this subscriber creation. Subject to aggressive rate limiting (5 per hour per newsletter).
Request body
The email address of the subscriber.
Any notes you want to attach to the subscriber. These are not publicly visible.
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.)
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 URL the subscriber was referred from (e.g. where they submitted the subscription form).
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.
The ID of the subscriber that referred this subscriber.
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.
The IP address of the subscriber. If provided, we will use this IP address to determine the subscriber's location and validate their legitimacy.
Example request
{
"email_address": "telemachus@buttondown.email",
"notes": "One of our first subscribers!",
"ip_address": "127.0.0.1"
}Response
Created
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 Buttondown has marked the subscriber as undeliverable. Undeliverable subscribers are not sent emails, and may be periodically removed from the system (or restored, if the reason is no longer valid.)
These reasons are grouped into three categories:
- PermanentFailure ("Failed (recipient)"): Address-based issues where the recipient is truly unreachable. Includes: HARD_BOUNCE
- MessageFailure ("Failed (message)"): Message/sender problems where future emails may succeed. Includes: ACCESS_DENIED, AUTHENTICATION_ISSUE, DELIVERY_EXPIRED, DOMAIN_BLOCKED, EMAIL_BLOCKED, IP_BLOCKED, ON_ESP_DENYLIST, OUT_OF_STORAGE, PROBLEMATIC_URL, SPAM
- Deferral (not shown to customers): Transient delivery issues that will be retried. Includes: RATE_LIMITED, TRANSIENT
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.
Represents the original provenance of a subscriber. This value is not exposed to subscribers; it's only used for internal tracking purposes and governs some of the behavior of the subscriber (i.e. whether or not to require double opt-in.)
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 ID of the registration form the subscriber signed up through, if any.
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.
When the subscriber was marked as undeliverable, if applicable.
The reason Buttondown has marked the subscriber as undeliverable. Undeliverable subscribers are not sent emails, and may be periodically removed from the system (or restored, if the reason is no longer valid.)
These reasons are grouped into three categories:
- PermanentFailure ("Failed (recipient)"): Address-based issues where the recipient is truly unreachable. Includes: HARD_BOUNCE
- MessageFailure ("Failed (message)"): Message/sender problems where future emails may succeed. Includes: ACCESS_DENIED, AUTHENTICATION_ISSUE, DELIVERY_EXPIRED, DOMAIN_BLOCKED, EMAIL_BLOCKED, IP_BLOCKED, ON_ESP_DENYLIST, OUT_OF_STORAGE, PROBLEMATIC_URL, SPAM
- Deferral (not shown to customers): Transient delivery issues that will be retried. Includes: RATE_LIMITED, TRANSIENT
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.
Example response
{
"country": "US",
"email_address": "telemachus@buttondown.email",
"delivered_count": 12,
"open_count": 7,
"clicked_count": 3,
"open_rate": 0.5833,
"click_rate": 0.25
}