Sinch SMS Batches & Delivery Reports
Send, schedule and track business SMS through Sinch: dry-run a batch to see how many parts each message costs, send it now or at a set time, then read per-recipient delivery reports and the replies that came back. Recipient groups keep your customer lists ready to reuse.
Connect this API to an AI agent Browse all specs
What you can do with Sinch SMS Batches & Delivery Reports via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| POST | /xms/v1/{service_plan_id}/batches/dry_run |
dryRunBatch | Preview a batch: message parts and encoding, without sending |
| POST | /xms/v1/{service_plan_id}/batches |
sendBatch | Send an SMS to one or many recipients, now or scheduled |
| GET | /xms/v1/{service_plan_id}/batches |
listBatches | List batches sent in the last 14 days |
| GET | /xms/v1/{service_plan_id}/batches/{batch_id} |
getBatch | Get a batch with its recipients, text and schedule |
| DELETE | /xms/v1/{service_plan_id}/batches/{batch_id} |
cancelBatch | Cancel a scheduled batch before it is sent |
| GET | /xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report |
getBatchDeliveryReport | Get delivery status counts for a batch |
| GET | /xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report/{recipient_msisdn} |
getRecipientDeliveryReport | Get the delivery status of one recipient in a batch |
| GET | /xms/v1/{service_plan_id}/delivery_reports |
listDeliveryReports | List delivery reports, filtered by date, status or error code |
| GET | /xms/v1/{service_plan_id}/inbounds |
listInboundMessages | List replies and other incoming messages |
| GET | /xms/v1/{service_plan_id}/inbounds/{inbound_id} |
getInboundMessage | Get one incoming message |
| GET | /xms/v1/{service_plan_id}/groups |
listGroups | List recipient groups |
| POST | /xms/v1/{service_plan_id}/groups |
createGroup | Create a recipient group, optionally with members |
| GET | /xms/v1/{service_plan_id}/groups/{group_id}/members |
listGroupMembers | List the phone numbers in a group |
Authentication
BearerAuth
Bearer token — sent as Authorization: Bearer <token>
Sinch SMS API token, sent as Authorization: Bearer <token>.
How to get a credential
- Sign up or sign in at https://dashboard.sinch.com (a free trial account works).
- Open SMS > APIs. Each service plan has a Service plan ID and an API token; click Show to reveal the token.
- Note the region shown for the service plan (US, EU, AU, BR or CA); the base URL must match it.
- Add a sender: a number you own in Sinch (trial accounts get a test number) or an approved alphanumeric sender id.
Permissions used
| Credential | Operations |
|---|---|
| API token of the service plan | every operation in this spec, scoped to that service_plan_id |
Common errors
- 401 Unauthorized: token wrong, or it belongs to another service plan. Copy both from the same row in the dashboard.
- 403 Forbidden: the region in the base URL does not match the service plan, or the trial account is sending to an unverified number.
- 400 Bad Request:
tonumbers must be E.164 (+15551234567);frommust be a sender the plan owns; checksyntax_errordetails. - 429 Too Many Requests: the plan's message rate was exceeded. Wait and retry.
Store the token as a bearer credential in VX Agents and pin service_plan_id as a preset; never paste the token into chat.
Usage guide
Setup
- Credential: the service plan's API token (Sinch dashboard > SMS > APIs), stored as a bearer credential.
- Pin
service_plan_id(same dashboard row as the token) as a preset parameter; every operation needs it. - Pick the server region that matches the service plan (
us,eu,au,br,ca); a mismatch returns 401/403. - Worth pinning as a default: your sender (
from), a Sinch number in E.164 or an approved alphanumeric id.
Send an SMS campaign and check delivery
- Draft the text with the user. Call
dryRunBatchwith the same body you plan to send (from,to,body) to see the number of parts and encoding per recipient (Unicode characters such as emoji make each part shorter and cost more). - Show recipients, text and part count, and ask for confirmation. Then
sendBatchwithfrom,to(array of E.164 numbers or group ids),body, and optionallysend_at(ISO-8601 UTC) to schedule it anddelivery_report: "summary"or"full". - Keep the returned batch
id.getBatchshows its state;cancelBatchstops a scheduled batch that has not gone out yet (confirm first). getBatchDeliveryReport(type=summaryfor counts,fullfor numbers per status) andgetRecipientDeliveryReportfor one phone number.listInboundMessages(filter byto= your sender number and a date range) to read replies;getInboundMessagefor one.- Reusable audiences:
listGroups,listGroupMembers, andcreateGroupwith aname(max 20 characters) andmembers.
Good to know
- Sending and cancelling affect real customers and cost money: always confirm first.
- Phone numbers are E.164 with a leading
+; group ids can be mixed intoto. - Times are ISO-8601 UTC;
listBatchesonly returns batches from the last 14 days. - Lists use zero-based
pageandpage_size(max 100). - Delivery statuses include
Queued,Dispatched,Delivered,Failed,Expired,Rejected;listDeliveryReportsfilters bystatusand errorcode. - The
parametersfield ofsendBatchfills per-recipient placeholders like${name}inbody. - Source: Sinch SMS API reference (https://developers.sinch.com/docs/sms/api-reference/sms), checked 2026-10-16.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Sinch SMS Batches & Delivery Reports” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.