Log in or sign up for an account

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 comments
delete_comments
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.
Success
processedThe bulk action has completed.
Error
failedThe bulk action was unable to be completed. Buttondown is looking into it.

Create Bulk Action

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/bulk_actions"


response = requests.post(f"{BASE_URL}{ENDPOINT}", headers=headers)

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."
}
409Conflict
{}

Retrieve Bulk Action

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/bulk_actions/{id}"


response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)

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."
}
404Not Found
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
409Conflict
{}