Send batch
send_batchSend one message to many people (a broadcast or campaign): pick recipients by segment_id, tags, contact_ids, or an explicit recipients list. Opted-out numbers, numbers without marketing consent, and people unsubscribed from topic_id are removed before sending. dry_run: true sends nothing and returns the count, cost, rejected rows and consent. scheduled_at sends at one instant; send_at_local (like 2026-11-10T17:00) sends at that time on each person's own clock.no_opt_in (recipients the send will skip for having no opt-in). Leave out from and TextKit picks a number approved for category (marketing unless you say otherwise), one per recipient; sender shows them, and with none approved it answers 400 and sends nothing. scheduled_at sends later (up to 30 days). shorten_links: true tracks link clicks: suggest it whenever the text has a link. Each recipient can carry external_id (their Mixpanel distinct_id) so the text's events land on their Mixpanel profile. With a live key it texts real people.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"body": "<body>"
},
"name": "send_batch"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The message text. Merge tags fill per recipient | |
| from | No | One of your numbers, to pin the batch to it. Leave it out and TextKit picks a number approved for `category` (marketing unless you say otherwise), the same one per recipient. Nothing approved is a 400. | |
| name | No | A name for the broadcast | |
| tags | No | Send to contacts carrying any of these tags (instead of recipients). | |
| dry_run | No | Validate only: returns a BatchValidation and sends nothing. | |
| list_id | No | Send to the contacts in this list, as it is when the batch is created (instead of recipients). | |
| category | No | Optional. It can make the batch stricter (`marketing`), never looser: the sending number's registration and the wording decide ([which messages are marketing](/docs/compliance-checks#which-messages-are-marketing)). From a number with no registration, a batch is marketing. | |
| topic_id | No | Subscription topic. Recipients unsubscribed from it are removed at validation (`topic_unsubscribed`) and skipped at send time, like opt-outs. Omit to apply opt-outs only. | |
| recipients | No | Explicit recipients, up to 10,000 | |
| segment_id | No | Send to the contacts in this saved segment, evaluated when the batch is created (instead of recipients). | |
| contact_ids | No | Send to these contacts, by id | |
| quiet_hours | No | Optional. What to do with a message in the recipient's quiet hours: `block` refuses it (403 quiet_hours), `defer` holds it until their next 9:00am. Omitted: each recipient in quiet hours is held until their 9:00am. | |
| scheduled_at | No | Future ISO timestamp or epoch ms, up to 30 days out. | |
| send_at_local | No | Instead of `scheduled_at`: a date and time with no time zone, up to 30 days out, sent at that time in each recipient's own zone, read from the area code. Refused if it has passed for any recipient. Quiet hours still hold a time outside the window. | |
| shorten_links | No | Optional. Rewrite every http(s) link to a tracked short link, per recipient, when each message is sent. Clicks show in GET /batches/{id}/results. | |
| check_line_types | No | Reject landlines (first 500 unique numbers are checked). |