BulkAction

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.

Basic bulk action

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

Bulk action to apply tags (which has a slightly different payload)

{
"creation_date": "2019-08-24T14:15:22Z",
"completion_date": "2019-08-24T14:17:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "completed",
"type": "apply_tags",
"metadata": {
"tag": "4931-4f5c-9b5b-2c9f6c9f6c9f",
"action": "add",
"ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
}
fieldtypedescription
idstring
creation_datestring
statusBulkActionStatus
typeBulkActionType
completion_datestring
metadataobject

Type (BulkActionType)

Represents the action being performed on a bulk of objects. (Not to be coy, but these names should be self-explanatory.)


typeidentifierdescription
Apply tags
apply_tagsThis 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 (to subscribers)
apply_metadataThis 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).
Ban subscribers
ban_subscribers
Delete emails
delete_emails
Delete subscribers
delete_subscribers
Delete tags
delete_tags
Reactivate subscribers
reactivate_subscribers
Replay events
replay_events
Resubscribe subscribers
resubscribe_subscribers
Send emails
send_emailsThis action requires one additional parameter within `metadata`: `email_id` (the ID of the email which you'd like to send).
Send reminders
send_reminders
Update email types
update_email_types
Unsubscribe subscribers
unsubscribe_subscribers

Status (BulkActionStatus)

Represents the status of a bulk action. No action is required to move from one state or another; Buttondown internally handles the transitions, and exposing the status is for observability purposes only.


typeidentifierdescription
Not started
not_startedThe bulk action has not yet started
In progress
in_progressThe bulk action is currently being processed
processed
processedThe bulk action has completed
failed
failedThe bulk action was unable to be completed. Buttondown is looking into it.

Create Bulk Action

$ curl -X POST https://api.buttondown.email/v1/bulk_actions

Parameters

parametertypedescriptionoptional
type
metadataobject

Responses

StatusDescriptionSample Response
201Created
{
"creation_date": "2019-08-24T14:15:22Z",
"completion_date": "2019-08-24T14:17:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "completed",
"type": "delete_subscribers",
"metadata": {
"ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
}
403Forbidden
{
"code": "something_went_wrong",
"detail": "Your call is very important to us."
}

Retrieve Bulk Action

$ curl -X GET https://api.buttondown.email/v1/bulk_actions/{pk}

Responses

StatusDescriptionSample Response
200OK
{
"creation_date": "2019-08-24T14:15:22Z",
"completion_date": "2019-08-24T14:17:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "completed",
"type": "delete_subscribers",
"metadata": {
"ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
}
403Forbidden
{
"code": "something_went_wrong",
"detail": "Your call is very important to us."
}