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"]}}
| field | type | description |
|---|---|---|
| id | string | |
| creation_date | string | |
| status | BulkActionStatus | |
| type | BulkActionType | |
| completion_date | string | |
| metadata | object |
Type (BulkActionType)
Represents the action being performed on a bulk of objects. (Not to be coy, but these names should be self-explanatory.)
| type | identifier | description |
|---|---|---|
Apply tags | 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 (to subscribers) | 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). |
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_emails | This 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.
| type | identifier | description |
|---|---|---|
Not started | not_started | The bulk action has not yet started |
In progress | in_progress | The bulk action is currently being processed |
processed | processed | The bulk action has completed |
failed | failed | The 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
| parameter | type | description | optional |
|---|---|---|---|
| type | |||
| metadata | object |
Responses
| Status | Description | Sample Response |
|---|---|---|
| 201 | Created |
|
| 400 | Bad Request |
|
| 403 | Forbidden |
|
Retrieve Bulk Action
curl -X GET https://api.buttondown.email/v1/bulk_actions/{pk}
Responses
| Status | Description | Sample Response |
|---|---|---|
| 200 | OK |
|
| 403 | Forbidden |
|