Send a batch of SMS messages
const url = 'https://api.connect.ms/v2/sms/batches';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"messages":[{"sender":"example","recipient":"example","content":"example","kind":"transactional","unicode":"allow","clientReference":"example","clientTag":"example"}],"defaults":{"sender":"example","kind":"transactional","clientTag":"example","scheduledAt":"2026-04-15T12:00:00Z","validitySeconds":1,"shortenLinks":true,"trackClicks":true,"bypassSuppressions":true,"link":{"include":true,"mode":"unsubscribe","preText":"example"}},"list":{"ids":["example"],"excludeIds":["example"]},"sender":"example","content":"example","template":{"name":"example","data":{"additionalProperty":"example"}},"kind":"transactional","clientReference":"example","clientTag":"example","scheduledAt":"2026-04-15T12:00:00Z","validitySeconds":1,"pacing":{"ratePerPeriod":1,"period":"hour"},"skipMessagedWithinHours":1,"shortenLinks":true,"trackClicks":true,"link":{"include":true,"mode":"unsubscribe","preText":"example"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.connect.ms/v2/sms/batches \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "messages": [ { "sender": "example", "recipient": "example", "content": "example", "kind": "transactional", "unicode": "allow", "clientReference": "example", "clientTag": "example" } ], "defaults": { "sender": "example", "kind": "transactional", "clientTag": "example", "scheduledAt": "2026-04-15T12:00:00Z", "validitySeconds": 1, "shortenLinks": true, "trackClicks": true, "bypassSuppressions": true, "link": { "include": true, "mode": "unsubscribe", "preText": "example" } }, "list": { "ids": [ "example" ], "excludeIds": [ "example" ] }, "sender": "example", "content": "example", "template": { "name": "example", "data": { "additionalProperty": "example" } }, "kind": "transactional", "clientReference": "example", "clientTag": "example", "scheduledAt": "2026-04-15T12:00:00Z", "validitySeconds": 1, "pacing": { "ratePerPeriod": 1, "period": "hour" }, "skipMessagedWithinHours": 1, "shortenLinks": true, "trackClicks": true, "link": { "include": true, "mode": "unsubscribe", "preText": "example" } }'Queues up to 1000 individual messages, or one message to the members of your contact lists, immediately, at scheduledAt or paced over time. Rows that fail validation are reported in errors while the rest are queued; the whole batch is rejected when no row is valid or 25 or more rows fail.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”The API version to use, for example 2026-10-01. Defaults to the version set on your API key.
A unique value of up to 255 characters, so a retried request is not acted on twice. Required for keys in Strict API Mode.
Request Bodyrequired
Section titled “Request Bodyrequired”A batch to send. Provide exactly one of messages (with defaults) and list (with the remaining fields, which apply to every contact).
A batch to send. Provide exactly one of messages (with defaults) and list (with the remaining fields, which apply to every contact).
object
The messages to send, between 1 and 1000. Cannot be combined with list.
One message in a batch. Fields left out fall back to the batch defaults.
object
Sender Name for the SMS. Falls back to defaults.sender.
Recipient Number (E.164 format) for the SMS.
The message text, up to 5,000 characters.
The kind of message: transactional (service messages, the default), marketing (promotional, subject to opt-outs and the unsubscribe link) or authentication (one-time codes).
How characters outside the GSM alphabet are handled: allow (send as written, using UCS-2 when needed), deny (reject the request if the content you send has any; a stored template is not checked), smart (replace curly quotes, dashes, ellipses and unusual spaces with GSM equivalents and remove emoji, leaving letters untouched) or strip (as smart, then fold accented letters that GSM lacks to their base letter and remove anything else outside the GSM alphabet, so the message always sends as GSM-7).
Your own reference for this individual message, up to 64 characters.
A grouping tag for this message, up to 64 characters. Stored in lower case with anything other than letters and digits replaced by hyphens.
Values applied to every message in the batch. A message’s own sender, kind or clientTag takes precedence.
object
Sender for messages that do not name their own: an approved sender name, a verified UK mobile number in 07 format, or one of your inbound numbers in E.164 format.
The kind of message: transactional (service messages, the default), marketing (promotional, subject to opt-outs and the unsubscribe link) or authentication (one-time codes).
A grouping tag applied to the batch for usage reporting, up to 64 characters. Stored in lower case with anything other than letters and digits replaced by hyphens.
When (UTC, ISO 8601) to send the batch: at least 5 minutes and at most 12 months ahead. If not specified, the batch is sent immediately.
How long each message stays eligible to send, between 60 and 172800 seconds. If omitted or 0 there is no window and messages the workspace cannot pay for fail immediately.
Whether to shorten links in the content. Omit to follow the workspace setting.
Whether to give each shortened link a tracking code for this message, so its clicks can be read per message. Every link is then shortened. Omit to follow the workspace setting; cannot be true when shortenLinks is false.
Send even to recipients on the suppression list. Defaults to false; a connected app cannot set it to true.
Overrides the workspace’s message link settings for this send.
object
Whether to append a link. Omit to follow the workspace setting; the link is never added to authentication messages, and a connected app cannot set this to false.
What the appended link offers the recipient: unsubscribe (opt out of marketing), reply (send a reply from the web) or both.
Text placed before the link, up to 64 characters. Omit to follow the workspace setting.
The contact lists to send to. Contacts in more than one list receive one message; contacts in an excluded list receive none.
object
Ids of the lists to send to, between 1 and 20.
Ids of lists whose members are left out, up to 20. A list cannot be both included and excluded.
Sender for a list send: an approved sender name, a verified UK mobile number in 07 format, or one of your inbound numbers in E.164 format.
The message text for a list send, up to 5,000 characters. Cannot be combined with template.name; contact fields can be used as merge fields.
The kind of message: transactional (service messages, the default), marketing (promotional, subject to opt-outs and the unsubscribe link) or authentication (one-time codes).
Your own reference applied to every message in a list send, up to 64 characters.
A grouping tag applied to every message in a list send, up to 64 characters. Stored in lower case with anything other than letters and digits replaced by hyphens.
When (UTC, ISO 8601) to send a list send: at least 5 minutes and at most 12 months ahead. If not specified, the batch is sent immediately.
How long each message of a list send stays eligible to send, between 60 and 172800 seconds. If omitted or 0 there is no window.
Skips contacts messaged within this many hours. One of 6, 12, 24, 48, 72 or 168.
Whether to shorten links in the content of a list send. Omit to follow the workspace setting.
For a list send: whether to give each shortened link a tracking code for this message, so its clicks can be read per message. Every link is then shortened. Omit to follow the workspace setting; cannot be true when shortenLinks is false.
Overrides the workspace’s message link settings for this send.
object
Whether to append a link. Omit to follow the workspace setting; the link is never added to authentication messages, and a connected app cannot set this to false.
What the appended link offers the recipient: unsubscribe (opt out of marketing), reply (send a reply from the web) or both.
Text placed before the link, up to 64 characters. Omit to follow the workspace setting.
Responses
Section titled “Responses”The batch was accepted for sending. The Location header holds its URL.
A batch of SMS messages. The same shape is returned by every batch endpoint and carried by batch.* events.
object
The unique id of the batch.
How the batch was created: api (a list of messages), import (an uploaded file) or list (contact lists).
The batch status: queued (nothing has been sent yet), sending (some messages have been sent, failed or cancelled and the batch is not yet complete), paused (paced delivery paused or messages held for payment), completed or cancelled.
Message counts for the batch by status. sent includes delivered; total is every row including skipped ones.
object
Every row in the batch, including skipped ones.
Messages not yet handed to the network.
Messages handed to the network and not since failed, including those delivered.
Messages confirmed delivered.
Messages that failed.
Rows that were never queued; see skipped for why.
Messages that were cancelled.
Why rows were skipped rather than queued.
object
Recipients on the suppression list.
Recipients messaged within the skipMessagedWithinHours window.
Rows that failed validation.
Paced delivery details.
object
How many messages are sent per period.
The period a pacing rate applies to: hour or day.
Why paced delivery is paused: user (paused from the dashboard), sending_blocked (the workspace cannot send), sender_revoked (the sender is no longer approved), api_key_limit (the API key’s send limit was reached) or payment_required (the workspace is out of credit).
When (UTC) the last message is expected to send at the current rate, or null when not known.
Why a message is waiting rather than sending.
object
Why a message is being held: payment_required (the workspace is out of credit; the message sends once credit is restored or fails when its validity window passes).
When (UTC) the hold began.
When (UTC) the message fails if the hold is not lifted, or null when it has no validity window. Always null on a batch.
Rows that were rejected, by position. Only populated on the response that created the batch; empty everywhere else.
A row of the request that was not accepted.
object
The zero-based position of the row in the submitted messages.
What was wrong with the row.
The grouping tag applied to the batch, for usage reporting. A message can carry its own tag instead.
When (UTC) the batch was asked to send, or null when no send time was given.
When (UTC) the batch was created.
When (UTC) the last message reached a final state, or null while messages remain.
When (UTC) the batch was cancelled, or null.
Example
{ "source": "api", "status": "queued", "paced": { "period": "hour", "pauseReason": "user" }, "hold": { "reason": "payment_required" }}The request is not valid. The detail field says why, and errors lists any problems by field name.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The API key or bearer token is missing or not valid, or the request signature could not be verified.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}Payment is required before the workspace can send this batch.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The caller is not allowed to do this, or sending is blocked for the workspace (sending_blocked).
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}One or more of the contact lists do not exist.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}A request with this Idempotency-Key is still being processed. Retry after the Retry-After header.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}This Idempotency-Key was already used for a different request. Use a new key.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}This API key requires an Idempotency-Key header on every POST and PATCH.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The API key’s send limit was reached. Retry after the Retry-After header.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The batch could not be queued right now. Retry after the Retry-After header.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}