Preview a batch of SMS messages
const url = 'https://api.connect.ms/v2/sms/batches/preview';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/preview \ --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" } }'Takes the same body as sending a batch and estimates what would happen: how many messages and parts, the estimated cost, and which rows would be skipped or rejected. Nothing is sent, and a list send’s template is measured as written rather than rendered.
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”What the batch would do.
An estimate of what a batch would do if sent: how many messages, how many parts, the estimated cost and what would be skipped. Checks made only at send time, such as sender approval, are not included.
object
How many messages would be queued.
The total SMS parts across those messages. For a list send, merge fields are counted as written, not rendered.
An amount in each currency it can be priced in, as decimal strings with four decimal places. A currency with no price is null.
object
The amount in pounds sterling, e.g. “0.0350”.
The amount in euros, e.g. “0.0410”.
Why rows were skipped rather than queued.
object
Recipients on the suppression list.
Recipients messaged within the skipMessagedWithinHours window.
Rows that failed validation.
Rows that would be rejected, by position. Always empty for a list send.
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.
True when the workspace would need to top up before this batch could send. Only checked for a list send; always false for individual messages.
When (UTC) a paced batch would finish sending, or null when it is not paced.
Example generated
{ "recipients": 1, "parts": 1, "cost": { "gbp": "example", "eur": "example" }, "skipped": { "suppressed": 1, "recentlyMessaged": 1, "invalid": 1 }, "errors": [ { "index": 1, "detail": "example" } ], "paymentRequired": true, "estimatedCompletionAt": "2026-04-15T12:00:00Z"}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"}The caller is not allowed to do this.
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 service is temporarily unavailable. 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"}