bulk_lead_action

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.

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.

create always asks for confirmation: 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: 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.

Get Started

Read Tools

Write Tools

Guides

`create` arguments

​create arguments

`create` arguments