Buttondown logo

Introduction

Statuses

flowchart
  not_started e1@--> in_progress
  in_progress e2@--> processed
  in_progress e3@--> failed
  e1@{ animate: true }
  e2@{ animate: true }
  e3@{ animate: true }

A bulk action represents, well, a bulk action. It is used to perform actions on a large number of objects at once. For example, you can use it to delete a large number of emails, or to unsubscribe a large number of subscribers. The actions within a bulk action are processed serially by Buttondown; this should be considered an ergonomic way to batch API calls across the network rather than a net-new piece of functionality in of itself.

{
    "creation_date": "2019-08-24T14:15:22Z",
    "completion_date": "2019-08-24T14:17:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "processed",
    "type": "delete_subscribers",
    "metadata": {
        "ids": [
            "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        ]
    }
}

Fields

idstring

A unique TypeID associated with the object.

creation_datestring

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

typestring · enum

The type of bulk action to perform.

values
  • add_notes

    Add notes to multiple subscribers in bulk.

  • apply_tags

    This action requires two additional parameters within metadata: tag_id (the ID of the tag which you'd like to either add or remove to the list of subscribers) and action (which can be either add or remove).

  • apply_metadata

    This action requires two additional parameters within metadata: action (which can be either add, set, or remove), and metadata (the value of the metadata which you'd like to either add or remove to the list of subscribers).

  • rename_metadata

    Rename multiple metadata fields in bulk. This action requires two additional parameters within metadata: rename_mapping field and an ids field (either a list of specific subscriber IDs for whom you want to rename metadata, or all).

  • ban_subscribers

    Ban subscribers from your newsletter.

  • delete_subscribers

    Delete multiple subscribers in bulk.

  • gift_subscribers

    Gift premium subscriptions to multiple subscribers in bulk.

  • ungift_subscribers

    Remove gifted premium subscriptions from multiple subscribers in bulk.

  • reactivate_subscribers

    Reactivate multiple subscribers in bulk.

  • mark_subscribers_as_not_spammy

    Restore the status of multiple subscribers. Their exact type will depend on their history with your newsletter, but in general Buttondown will do the 'right' thing (e.g. restoring their premium subscription if they had one.)

  • resubscribe_subscribers

    Resubscribe multiple unsubscribed subscribers in bulk.

  • send_emails

    This action requires one additional parameter within metadata: email_id (the ID of the email which you'd like to send).

  • unban_subscribers

    Unban multiple subscribers in bulk.

  • send_reminders

    Send reminders to multiple subscribers in bulk.

  • unsubscribe_subscribers

    Unsubscribe multiple subscribers in bulk.

  • delete_attachments

    Delete multiple uploaded attachments in bulk.

  • delete_emails

    Delete multiple emails in bulk.

  • delete_images

    Delete multiple uploaded images in bulk.

  • update_email_types

    Update the email types for multiple emails in bulk.

  • update_archival_modes

    Update the archival modes for multiple emails in bulk.

  • update_commenting_modes

    Update the commenting modes for multiple emails in bulk.

  • mark_inbox_items_read

    Mark multiple inbox items as read.

  • delete_inbox_items

    Delete multiple inbox items in bulk.

  • change_tags_colors

    Change the color of multiple tags in bulk.

  • delete_comments

    Delete multiple comments in bulk.

  • delete_surveys

    Delete multiple surveys in bulk.

  • delete_survey_responses

    Delete multiple survey responses in bulk.

  • delete_tags

    Delete multiple tags in bulk.

  • mark_comments_as_active

    Mark multiple comments as active.

  • mark_comments_as_spammy

    Mark multiple comments as spam.

  • replay_events

    Replay multiple events in bulk.

  • update_survey_statuses

    Update the status types for multiple surveys in bulk.

  • cancel_stripe_subscriptions

    Cancel the Stripe subscriptions for multiple subscribers in bulk.

  • modify_stripe_subscriptions

    Modify the Stripe subscriptions for multiple subscribers in bulk.

  • pause_stripe_subscriptions

    Pause or unpause the Stripe subscriptions for multiple subscribers in bulk.

metadataobject

Parameters for the bulk action. The exact shape depends on type — typically an ids list of object IDs to act on.

statusstring · enum

The current processing status of the bulk action.

values
  • not_started

    The bulk action has not yet started.

  • in_progress

    The bulk action is currently being processed.

  • processed

    The bulk action has completed.

  • failed

    The bulk action was unable to be completed. Buttondown is looking into it.

completion_datestring

The date and time at which the bulk action was completed.