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

python
ruby
curl
Copy to clipboard
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"
]
}
}
400Bad Request
{
"code": "something_went_wrong",
"detail": "Your call is very important to us."
}
403Forbidden
{
"code": "something_went_wrong",
"detail": "Your call is very important to us."
}

Retrieve Bulk Action

python
ruby
curl
Copy to clipboard
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."
}