> ## Documentation Index
> Fetch the complete documentation index at: https://developer.lofty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bulk_lead_action

> Queue a mass SMS, mass email, tag change or pipeline-stage change across up to 5,000 leads, then check its progress.

> [!WARNING]
>
> **WRITE** · 2 operations · may change data

Queue a mass SMS, mass email, tag change or pipeline-stage change across up to 5,000 leads, then check its progress.

```js theme={null}
bulk_lead_action({
  action: "create" | "status",
  type?, lead_ids?, params?, plan_id?, confirm_token?
})
```

| Call | Does | Confirms? |
| - | - | - |
| `{action:"create", type, lead_ids, params}` | Queues a mass action plan | **Always** |
| `{action:"status", plan_id}` | Reads a plan's progress | No |

`create` is asynchronous. Its result confirms that a plan was queued and returns the plan's `planId`, `type` and `name`. It does not mean any message was sent or any lead was updated — that happens afterward, over time. Pass the `planId` to `status` to read the plan's status and its task counts by outcome. `status` only returns plans you created.

## `create` arguments

| Parameter | Required | Notes |
| - | - | - |
| `type` | Yes | `sms`, `email`, `tag` or `pipeline`. |
| `lead_ids` | Yes | Target lead ids, 1 to 5,000. |
| `params` | Yes | Depends on `type` — see below. |
| `confirm_token` | — | The token from the confirmation response, on the second call. |

| `type` | `params` |
| - | - |
| `sms` | `content` (required) — the text message body. |
| `email` | `subject` and `content` (both required). |
| `tag` | `tagsAdd` and/or `tagsRemove` — string arrays; at least one must be non-empty. |
| `pipeline` | `stage` (required) — the target pipeline stage name. |

A missing or blank required parameter is rejected before the call reaches the backend. A tag or pipeline stage name that does not exist is rejected with `20012`.

> [!WARNING]
>
> `create` always asks for [confirmation](https://developer.lofty.com/mcp/guides/confirmation-tiers.md): the first call returns `needsConfirmation` with a summary of the action and the lead count; call again with the same arguments plus `confirm_token` to queue it. A queued plan cannot be recalled once it starts sending or updating.

This is the one tool that is not bound by the [10-record cap](https://developer.lofty.com/mcp/guides/bulk-writes.md): the work runs as a single plan on the server rather than one write per record, and the lead set is always an explicit list of ids, never a filter.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.