Sign in
Subscribers

Retrieve Subscriber

Retrieve a specific subscriber by their ID or email address

get/subscribers/{id_or_email}

Path parameters

id_or_emailstring required

Query parameters

expandstring[]

If provided, expand the given field.

If provided, expand the given field.

Response

OK

idstring required

A unique TypeID associated with the object.

creation_datestring date-time required

The date and time at which the object was first created.

avatar_urlstring nullable

URL of the subscriber's avatar image (e.g. a Gravatar URL), if available.

bounce_datestring date-time nullable

The date of the subscriber's most recent bounce event. May be set even if the subscriber has not yet been marked as undeliverable.

bounce_reason'access_denied' | 'authentication_issue' | 'delivery_expired' | 'domain_blocked' | 'email_blocked' | 'hard_bounce' | 'ip_blocked' | 'ip_undeliverable' | 'malformed' | 'on_esp_denylist' | 'other' | 'out_of_storage' | 'problematic_url' | 'rate_limited' | 'spam' | 'transient' | 'disabled' | 'does_not_exist' | 'spf_failed' | 'unreachable'

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
churn_datestring date-time nullable

When the subscriber cancelled their paid subscription, if applicable.

commenting_disabledboolean

Whether this subscriber is prevented from commenting.

countrystring nullable

The ISO 3166-1 alpha-2 country code inferred from the subscriber's IP address at signup, if available.

email_addressstring required

The email address of the subscriber.

gift_subscription_end_datestring date-time nullable

When the subscriber's gift subscription expires, if applicable.

gift_subscription_messagestring nullable

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

ip_addressstring nullable

The IP address recorded when the subscriber signed up, if available.

last_click_datestring date-time nullable

When the subscriber most recently clicked a link in an email.

last_open_datestring date-time nullable

When the subscriber most recently opened an email.

delivered_countinteger nullable

The number of distinct emails — both broadcasts and automation sends — delivered to this subscriber. Cached and refreshed periodically, so it may lag recent activity.

open_countinteger nullable

The subscriber's open count.

clicked_countinteger nullable

The subscriber's clicked count.

open_ratenumber nullable

The subscriber's open rate, computed from engagement counts. Null if delivered_count is 0 or null.

click_ratenumber nullable

The subscriber's click rate, computed from engagement counts. Null if delivered_count is 0 or null.

metadataobject

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

notesstring

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

purchased_bystring nullable

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

purchased_messagestring nullable

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

referral_codestring required

The subscriber's unique referral code, used to attribute referred signups.

referrer_urlstring

The URL the subscriber was referred from (e.g. where they submitted the subscription form).

risk_scorenumber nullable

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

secondary_idinteger required

A human-readable sequential identifier, unique within the newsletter.

source'admin' | 'api' | 'carrd' | 'comment' | 'embedded_form' | 'form' | 'import' | 'memberful' | 'netlify' | 'organic' | 'patreon' | 'shopify' | 'stripe' | 'user' | 'zapier' required

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

stripe_customer_idstring nullable

The Stripe customer ID associated with the subscriber, if any.

subscriber_import_idstring nullable

The ID of the subscriber import that created this subscriber, if any.

tagsstring[] required

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

form_idstring nullable

The ID of the registration form the subscriber signed up through, if any.

type'blocked' | 'complained' | 'churning' | 'churned' | 'gifted' | 'unactivated' | 'unpaid' | 'undeliverable' | 'premium' | 'past_due' | 'paused' | 'regular' | 'removed' | 'trialed' | 'unsubscribed' | 'upcoming' required

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.

undeliverability_datestring date-time nullable

When the subscriber was marked as undeliverable, if applicable.

undeliverability_reason'access_denied' | 'authentication_issue' | 'delivery_expired' | 'domain_blocked' | 'email_blocked' | 'hard_bounce' | 'ip_blocked' | 'ip_undeliverable' | 'malformed' | 'on_esp_denylist' | 'other' | 'out_of_storage' | 'problematic_url' | 'rate_limited' | 'spam' | 'transient' | 'disabled' | 'does_not_exist' | 'spf_failed' | 'unreachable'

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
unsubscription_datestring date-time nullable

When the subscriber unsubscribed, if applicable.

unsubscription_reasonstring nullable

Free-text reason the subscriber unsubscribed, if provided.

upgrade_datestring date-time nullable

When the subscriber upgraded to a paid subscription, if applicable.

utm_campaignstring required

The UTM campaign the subscriber was attributed to at signup.

utm_mediumstring required

The UTM medium the subscriber was attributed to at signup.

utm_sourcestring required

The UTM source the subscriber was attributed to at signup.

stripe_customerobject nullable

If expanded, the Stripe customer associated with this subscriber.

stripe_subscriptionobject nullable

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
}

Changes

Changed in 3 of the 11 revisions of this API.42

  • e0ac41d864642See the full diff
    • ○

      removed the email_address_cleantalk_score enum value from the firewall_reasons/items/code response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the ip_address_cleantalk_score enum value from the firewall_reasons/items/code response property for the response status 200

      response-property-enum-value-removed

  • 3a702c095d223See the full diff
    • ●

      added the new email_address_plus_variant_accounts enum value to the firewall_reasons/items/code response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new registration_without_prior_page_visit enum value to the firewall_reasons/items/code response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new username_shannon_entropy enum value to the firewall_reasons/items/code response property for the response status 200

      response-property-enum-value-added

  • 71b271a0f44a1See the full diff
    • ●

      added the new email_address_domain_burst enum value to the firewall_reasons/items/code response property for the response status 200

      response-property-enum-value-added