Cancel an SMS
const url = 'https://api.connect.ms/v2/sms/example';const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request DELETE \ --url https://api.connect.ms/v2/sms/example \ --header 'Authorization: Bearer <token>'Stops a message that is still waiting to send: one that is queued, scheduled, paced or held. A message being sent, already sent or in a final state cannot be cancelled.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The id of the message.
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.
Responses
Section titled “Responses”The message, now cancelled.
An SMS message, outbound or inbound. The same shape is returned by every SMS endpoint and carried by sms.* events.
object
The unique id of the message.
Which way the message travelled: outbound (sent by you) or inbound (received on one of your numbers, or as a reply through a message link).
The kind of message: transactional (service messages, the default), marketing (promotional, subject to opt-outs and the unsubscribe link) or authentication (one-time codes).
The sender: your sender name or number for outbound, the sending number (E.164 format) for inbound. Null for an inbound message when the caller may not see recipients.
The recipient number (E.164 format) for outbound, or your receiving number (or sender name, for a web reply) for inbound. Null for an outbound message when the caller may not see recipients.
The ISO 3166-1 alpha-2 country of the other party’s number, or null when it cannot be determined.
The message text as sent or received. Null when the caller may not see content.
How an inbound message arrived: sms (a text to one of your numbers) or web (a reply through a message link).
The message status: queued (accepted, scheduled, paced or held and not yet handed to the network), sent (handed to the network, awaiting a delivery receipt), delivered, failed (see reason), cancelled, or received for an inbound message.
Why a message failed.
object
Why a message failed: invalid (bad number, sender or parameter), blocked (a workspace or platform rule), rejected (no route or the destination country is not enabled), unreachable (the handset could not be reached in time), undeliverable (the network gave no usable reason) or expired (the validity window passed before it could be sent).
The specific error code in snake_case, e.g. invalid_destination_address or payment_required.
A short explanation of the failure.
True when the failure was not caused by the message or the recipient, so sending it again later may succeed.
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.
The number of SMS parts the content is split into.
How the content is encoded on the network: gsm7 (the standard alphabet, 160 characters in a single-part message) or ucs2 (70 characters in a single-part message, used when the content has characters outside the GSM alphabet).
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”.
Your own reference for this message, as supplied when it was sent.
The grouping tag for usage reporting, as stored when the message was sent (lower case, letters, digits and hyphens).
The id of the batch the message belongs to, or null when it was sent on its own.
How long the message stays eligible to send, in seconds. Null when no validity window was requested.
When (UTC) the validity window ends and the message fails if not yet sent. Null when there is no window, or while a paced message is waiting for its turn.
When (UTC) the message was created.
When (UTC) the message was asked to send, or null when no send time was given.
When (UTC) the message was handed to the network, or null if not yet sent.
When (UTC) the network confirmed delivery, or null if not delivered.
When (UTC) an inbound message was received. Null for outbound messages.
When (UTC) the message last changed.
Example
{ "direction": "outbound", "kind": "transactional", "channel": "sms", "status": "queued", "reason": { "category": "invalid" }, "hold": { "reason": "payment_required" }, "encoding": "gsm7"}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"}No message with that id.
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 message is being sent, has been sent or is in a final state, so it can no longer be cancelled.
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"}