Skip to main content
Use /bulk-tasks when your recipient list exceeds the existing 1,000-recipient batch limit. One task accepts up to 100,000 recipients. It stores numbered upload chunks and prepares smaller child batches in the background after you explicitly start it. The existing /batches and /sms-batches endpoints keep their limits.

Create an upload-only task

POST /bulk-tasks requires Idempotency-Key. Choose kind: sms or kind: calls. SMS uses recipient_format: recipients; calls accept either recipients or contact_ids. options uses the corresponding existing batch settings, including schedules, per-recipient variables, references, callbacks and test_mode.
Creating and uploading do not send messages or dial. Call tasks use options.agent_id. Every mutation requires batches:write for calls or sms:send for SMS. Reads require the corresponding batches:read or sms:read; having a scope for the other kind grants no access.

Upload the complete recipient list

Send PUT /bulk-tasks/{task_id}/chunks/{chunk_index} with {"recipients": [...]}. Indexes start at 0. Every chunk must contain exactly upload_chunk_size recipients, except the last chunk. For a call task using contact_ids, the array contains UUID strings. Otherwise it contains the existing inline call or SMS recipient objects. Upload sequentially. An unchanged index and body is safe to retry with the same key, including after a timeout. Different content at an existing index returns 409 idempotency_conflict. Duplicate phones, contact IDs and inline call external identities anywhere in a task reject the entire new chunk. The creating API key must perform uploads and start.
Each JSON request must fit the existing 1 MiB limit. Select a smaller upload_chunk_size (1–1,000) when recipient variables are large. If interrupted, resume using the same task, indexes, bodies and idempotency keys. Handle 429 using the rate-limit response headers.

Start background execution

Send POST /bulk-tasks/{task_id}/start with {} and an Idempotency-Key. An incomplete upload returns 400 validation_error with upload_incomplete. Starting again is safe and never duplicates the task’s child batches.
Starting a task authorizes real SMS sending or AI phone calls to its recipients, at its configured time. Use test_mode: true while integrating; it creates test results without carrier sends, dial commands or charges.
The scheduled worker prepares up to 10 SMS recipients or 100 call recipients per part, checking current key authority and destination rules. Revoked or expired keys prevent future parts from being submitted. The existing carrier, billing, call concurrency, calling-window and retry rules still apply. Large tasks may take multiple worker cycles; a requested schedule does not promise simultaneous delivery. Only one bulk call child per organization is active at a time, across all of its tasks, so a large task cannot fill the shared dialer shortlist. SMS preparation waits until its start time and pauses when the due delivery backlog reaches 500 recipients; this prevents mass preparation from outrunning the existing delivery worker and expiring unsent messages. Preparation runs on its own authenticated minute schedule with a 24-second cancellation deadline.

Track progress and investigate failures

GET /bulk-tasks/{task_id} reports uploaded_recipients, submitted_recipients, settled_recipients, failed_recipients, unknown_recipients and part counts. completed means every recipient has a settled result, including failures. It does not mean every SMS was delivered or every call was answered. Unknown SMS delivery remains unsettled; do not resend it in a new task. GET /bulk-tasks/{task_id}/parts returns at most 100 parts. Follow next_after using ?after=.... Each submitted part includes batch_id, which uses the existing SMS or call batch query endpoints. Failed preparation parts include a fixed error_code; failed_recipients counts execution failures, while failed_parts identifies preparation failures that never submitted recipients. Preparation failures make the task failed; previously submitted and other pending parts may continue. Task-wide cancellation and automatic replay of permanently failed parts are not provided. Use existing call batch pause/cancel endpoints for submitted call parts. Canonical contacts that resolve to the same person across call parts are rejected before that part starts. Never recreate the entire task to retry a partial or uncertain result. The MCP equivalents are brightalk_create_bulk_task, brightalk_upload_bulk_task_chunk, brightalk_start_bulk_task, brightalk_get_bulk_task and brightalk_list_bulk_task_parts.