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

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

parameter	type	description	optional
type
metadata	object

Responses

Status	Description	Sample Response
201	Created	{ "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" ] } }
400	Bad Request	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Status

Description

Sample Response

201

Created

{
    "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"
        ]
    }
}

400

Bad Request

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

403

Forbidden

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

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/{pk}"

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

Responses

Status	Description	Sample Response
200	OK	{ "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" ] } }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Status

Description

Sample Response

200

{
    "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"
        ]
    }
}

403

Forbidden

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

404

Not Found

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

On this page

Enums

Endpoints