Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Queue personalized batch messages

POST /api/v1/messages/batch queues personalized recipients instead of issuing one synchronous request per contact. It requires messages:write and an Idempotency-Key. The default configured maximum is 1,000 recipients per batch; an operator can set a different limit.

Build the request

Batch-level fields include channel, optional template, email sender, and list_id. The messages array contains one object per recipient. One channel selection applies to the whole batch; smart may route individual phone recipients differently.
Recipient fields include to, message or template variables, email subject, WhatsApp media_url, unique reference, optional profile fields/custom fields, and genuine whatsapp_opt_in where needed.
{
  "channel": "whatsapp",
  "messages": [
    {"to": "+2348012345678", "message": "Hi Ada, order 1201 shipped.", "reference": "order-1201"},
    {"to": "+2348098765432", "message": "Hi Tobi, order 1202 shipped.", "reference": "order-1202"}
  ]
}
This is a live queueing request. Do not assume the single-message test: true option is a batch simulation contract. Use a controlled small audience when proving batch delivery.

Understand partial acceptance

HTTP 202 Accepted means queued. The response includes batch_id, queue status, counts, accepted recipients, rejected recipients, and reserved cost. Accepted entries carry their input index and reference for correlation.
One invalid row does not necessarily reject the whole batch. Inspect every rejected entry's index, destination, and error code. Fix and resubmit only rejected recipients as a new logical request; replaying accepted entries with a new key can duplicate them.

Poll or subscribe

GET /api/v1/messages/batch/:batch_id returns counts and recipient outcomes, including references, provider IDs, status, and errors. Prefer delivery webhooks when your application otherwise polls continuously.
Queued work is paced per provider. Connected-number WhatsApp is deliberately slower and jittered; Meta Cloud, SMS, and email have their own limits. Do not parallelize batches to evade pacing.

Billing and retries

Accepted recipients reserve funds/allowance under the existing billing flow. Captures and releases follow delivery outcomes; recipients beyond available funds can be rejected with insufficient_balance rather than silently dropped.
Retry an identical uncertain submission with its original key. Keep your batch ID and recipient references after acceptance. Investigate an ambiguous provider outcome through the existing record before creating another message.
Next: use idempotency, webhooks, and billing.
A 202 response is not delivery confirmation. Track each recipient, including rejected rows, before marking an application job complete.