Buttondown logo

Introduction

Attempt errors

The attempt's error field contains one of these codes when it is skipped or fails. It is null if the attempt succeeded, hasn't run yet, or was skipped manually.

Codes are case-sensitive; match the exact string.

values
  • action_malformed

    The automation's action could not be carried out. For a POST-request action this usually means the request itself failed.

  • action_malformed__missing_recipient

    The automation is set to send an email but has no recipient configured.

  • action_malformed__missing_tag_ids

    The automation is set to change tags but has no tags configured.

  • action_malformed__missing_url

    The automation is set to send a POST request but has no URL configured.

  • action_malformed__unsupported_action_type

    The automation's action is not one that its trigger can perform.

  • EMAIL_ALREADY_SENT

    The subscriber had already been sent this email, so the automation left them alone.

  • EMAIL_DOES_NOT_EXIST

    The email this automation was set to send no longer exists.

  • EMAIL_EMPTY

    The email this automation was set to send has no content.

  • EMAIL_INVALID_STATUS

    The email this automation was set to send is in a state that cannot be sent.

  • event_malformed

    The event that triggered this automation is missing the data its action needs.

  • ID_DOES_NOT_EXIST

    One of the tags this automation was set to apply no longer exists.

  • INVALID_SUBSCRIBER

    The subscriber was not eligible to receive the email — they had unsubscribed, bounced, or never confirmed — so the automation left them alone. Recorded only by automation runs from before June 2024.

  • arena.misconfigured

    The automation posts to Are.na, but this newsletter has no Are.na credentials configured.

  • bluesky.misconfigured

    The automation posts to Bluesky, but this newsletter has no Bluesky credentials configured.

  • misconfigured__discord

    The automation posts to Discord, but this newsletter has no Discord credentials configured.

  • misconfigured__github

    The automation acts on GitHub, but this newsletter has no GitHub credentials configured.

  • misconfigured__linkedin

    The automation posts to LinkedIn, but this newsletter has no LinkedIn credentials configured.

  • mastodon.misconfigured

    The automation posts to Mastodon, but this newsletter has no Mastodon credentials configured.

  • misconfigured__shopify

    The automation acts on Shopify, but this newsletter has no Shopify credentials configured.

  • tumblr.misconfigured

    The automation posts to Tumblr, but this newsletter has no Tumblr credentials configured.

  • twitter.misconfigured

    The automation posts to Twitter, but this newsletter has no Twitter credentials configured.

  • NEWSLETTER_DISABLED

    The newsletter was disabled, so no email could be sent.

  • not_found

    Shopify had no customer matching this subscriber's email address.

  • rate_limit

    Shopify rate-limited the request.

  • unauthorized

    Shopify rejected this newsletter's API credentials.

  • stripe_subscription_does_not_exist

    The Stripe subscription this event referenced no longer exists.

  • SUBSCRIBER_INVALID

    The subscriber was not eligible to receive the email — they had unsubscribed, bounced, or never confirmed — so the automation left them alone.

  • TAG_ALREADY_EXISTS

    The subscriber already had one of the tags this automation applies.

  • unexpected_error

    Something went wrong that Buttondown did not anticipate. The failure is logged for us to look into.

A rule that automatically performs actions in response to events.

{
    "id": "aut_0k28edc3fw896bp4mrhc535z5k",
    "creation_date": "2000-01-01T00:00:00+00:00",
    "name": "Welcome email",
    "status": "inactive",
    "trigger": "subscriber.confirmed",
    "actions": [
        {
            "type": "send_email",
            "metadata": {
                "email_id": "em_0k28edc3fw896bp4mrhc535z5k"
            },
            "timing": {
                "time": "immediate",
                "delay": null
            }
        }
    ],
    "filters": {
        "filters": [],
        "groups": [],
        "predicate": "and"
    },
    "metadata": {},
    "should_evaluate_filter_after_delay": false
}

Fields

idstring

A unique TypeID associated with the object.

creation_datestring

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

namestring

The name of the automation.

statusstring · enum

Whether the automation is enabled or disabled.

values
  • active

    Active.

  • inactive

    Inactive.

triggerstring · enum

The event that causes this automation to run.

values
  • advertising_slot.inquiry

    Whenever a sponsor submits an inquiry for an advertising slot.

  • advertising_slot.purchased

    Whenever an advertising slot in your newsletter is purchased.

  • automation.invoked

    Whenever an automation is manually invoked (e.g. by a webhook or API call).

  • date.day.started

    Whenever a new day starts. This event is fired at midnight UTC.

  • date.month.started

    Whenever a new month starts. This event is fired at midnight UTC on the first day of each month.

  • date.week.started

    Whenever a new week starts. This event is fired at midnight UTC on Monday.

  • date.year.started

    Whenever a new year starts. This event is fired at midnight UTC on January 1st.

  • bigcommerce.customer.created

    Whenever a new customer is synced from BigCommerce.

  • bigcommerce.customer.updated

    Whenever a customer's data is updated in BigCommerce.

  • bigcommerce.order.created

    Whenever a new order is synced from BigCommerce.

  • bigcommerce.order.updated

    Whenever an order's data is updated in BigCommerce.

  • email.created

    Whenever a new email is created and begins delivery. Note that event happens immediately before the emails themselves are sent.

  • email.deleted

    Whenever an email has been deleted.

  • email.send.started

    Whenever an email starts sending. This fires as soon as the send is underway, before any recipient has been delivered to — useful for cross-posting, which otherwise waits for the whole send to finish.

  • email.sent

    Whenever an email has finished its delivery. Note that event happens immediately after all emails have been sent, but some email events may not have finished processing.

  • email.status.changed

    Whenever an email's status has changed (e.g. from 'draft' to 'sent'.) The metadata field will contain the previous and new statii in 'old_value' and 'new_value' respectively.

  • email.updated

    Whenever an email's content or metadata has been updated.

  • external_feed_item.created

    Whenever a new item is created in an RSS feed.

  • export.completed

    Whenever an export is completed.

  • export.created

    Whenever an export is created.

  • export.failed

    Whenever an export fails.

  • firewall.blocked

    Represents an incoming request that was blocked by the firewall.

  • mention.created

    Whenever your newsletter is mentioned elsewhere.

  • memberful.member.updated

    Whenever a member changes their email address in Memberful.

  • memberful.subscription.created

    Whenever a new subscription is created in Memberful.

  • memberful.subscription.deleted

    Whenever a subscription is deleted in Memberful.

  • note.created

    Whenever a note is created.

  • note.deleted

    Whenever a note is deleted.

  • patreon.member.updated

    Whenever a member changes their email address in Patreon.

  • patreon.membership.created

    Whenever a new membership is created in Patreon.

  • patreon.membership.deleted

    Whenever a membership is deleted in Patreon.

  • shopify.customer.created

    Whenever a new customer is created in Shopify.

  • shopify.customer.updated

    Whenever a customer changes their email address in Shopify.

  • social_mention.created

    Whenever your newsletter is mentioned on another website such as Reddit, Twitter, Bluesky, etc.

  • stripe.checkout.session.completed

    Whenever a Stripe checkout session is completed successfully.

  • stripe.customer.updated

    Whenever a customer changes their email address in Stripe.

  • stripe.invoice.upcoming

    When a paid subscriber's subscription is approaching its renewal date, mapped from Stripe's invoice.upcoming webhook. Lets you message subscribers before they're charged again.

  • stripe.subscription.activated

    Whenever a subscription is activated in Stripe.

  • stripe.subscription.churning

    Whenever a subscription is churning in Stripe.

  • stripe.subscription.deactivated

    Whenever a subscription is deactivated in Stripe.

  • subscriber.activation_bounced

    When a subscriber's confirmation (opt-in) email bounced.

  • subscriber.activation_clicked

    When a subscriber clicked a link in their confirmation (opt-in) email.

  • subscriber.activation_complained

    When a subscriber marked their confirmation (opt-in) email as spam.

  • subscriber.activation_deferred

    When a subscriber's confirmation (opt-in) email was deferred (a transient delivery failure the provider will retry).

  • subscriber.activation_delivered

    When a subscriber's confirmation (opt-in) email was successfully delivered.

  • subscriber.activation_opened

    When a subscriber opened their confirmation (opt-in) email.

  • subscriber.activation_rejected

    When a subscriber's confirmation (opt-in) email was rejected (a permanent delivery failure).

  • subscriber.bounced

    Whenever a subscriber's email is bounced.

  • subscriber.changed_email

    When a subscriber's email address has been changed.

  • subscriber.churned

    When a subscriber has unenrolled from your newsletter's paid offering.

  • subscriber.clicked

    When a subscriber has clicked a link in one of your emails.

  • subscriber.commented

    When a subscriber has commented on one of your emails.

  • subscriber.complained

    Whenever a subscriber has complained about one of your emails.

  • subscriber.confirmed

    When a subscriber has confirmed that they are enrolled in your newsletter. (For newsletters without double opt-in, this event is created immediately after subscriber.created.)

  • subscriber.created

    Whenever a new subscriber is created.

  • subscriber.deferred

    When a subscriber's email was deferred (a transient delivery failure the email provider will retry).

  • subscriber.deleted

    When a subscriber has been deleted from your newsletter.

  • subscriber.delivered

    Whenever a subscriber's email is successfully delivered.

  • subscriber.opened

    When a subscriber has opened one of your emails.

  • subscriber.paid

    When a subscriber has enrolled in your newsletter's paid offering.

  • subscriber.paused

    When a subscriber has paused their subscription.

  • subscriber.resumed

    When a subscriber has resumed their subscription after pausing it.

  • subscriber.referred

    When a subscriber has referred someone to your newsletter.

  • subscriber.referred.paid

    When a subscriber's referral has converted to a paid subscription.

  • subscriber.rejected

    Whenever a subscriber (or their email provider) has rejected an email from your newsletter. Buttondown takes rejections seriously, and will likely block the subscriber's email address from future emails and/or mark them as undeliverable.

  • subscriber.replied

    Whenever a subscriber has replied to one of your emails.

  • subscriber.sent

    Whenever an email has been sent to a subscriber.

  • subscriber.responded_to_survey

    When a subscriber has responded to a survey in your newsletter.

  • subscriber.tags.changed

    When a subscriber's tags have been modified.

  • subscriber.trial_ended

    When the trial has ended for a subscriber.

  • subscriber.trial_started

    When the trial has started for a subscriber. (For newsletters with automatic free trials, this will be created immediately after subscriber.confirmed.)

  • subscriber.type.changed

    When a subscriber's type has been changed.

  • subscriber.unsubscribed

    When a subscriber has manually unsubscribed from your newsletter.

  • subscriber.updated

    When a subscriber's notes or metadata has changed.

  • subscriber.viewed_checkout_page

    When a subscriber has viewed your checkout page.

  • survey.cleared_responses

    Whenever a survey's responses have been cleared.

  • survey.created

    Whenever a new survey is created.

  • survey.deleted

    Whenever a survey has been deleted.

  • survey.updated

    Whenever a survey's content or metadata has been updated.

  • form.created

    Whenever a new form is created.

  • form.deleted

    Whenever a form has been deleted.

  • form.updated

    Whenever a form's content or metadata has been updated.

actionsarray

The actions to perform when the trigger fires.

filtersFilterGroup

Conditions that must be met for the automation to run.

metadataobject

Additional metadata for the automation.

should_evaluate_filter_after_delayboolean

If true, filters are re-evaluated after the delay has passed.