Cancel a scheduled message

Calls off a message you scheduled with scheduled_at, before it is released for sending. The message moves to CANCELLED, which is terminal, and it is never sent.

Only a SCHEDULED message can be cancelled. A message that has already been released — queued, in flight, or finished — returns 409. The release sweeper runs continuously, so a cancellation sent within about a minute of the scheduled instant can lose that race and be refused; cancel with time to spare.

One message per call. A send to many recipients, or on several channels, becomes one message per recipient × channel, each with its own id; cancel the ones you want stopped. There is no bulk cancellation.

Cancelling is free, and nothing was charged for the hold in the first place — a scheduled message is only priced and billed at release.

A cancellation fires message.cancelled on your webhook, exactly once, carrying the scheduled_at that was called off so a consumer can un-record the send it was expecting. Cancelling the same message again returns this same response and fires no second event. Idempotency-Key is honoured.

A cancelled message cannot be resent — send a new one.

The response is the message itself, in the same shape GET /v3/messages/{id} returns, so the status you read back is the one now stored on the row, and scheduled_at is the time it would have gone out. GET /v3/messages/{id} keeps reporting both afterwards.

events is the message lifecycle as it stood immediately before the cancellation: the CANCELLED entry is written asynchronously and lands a moment later, so read status for the outcome. If you need the entry itself, re-fetch the message after a few seconds — GET /v3/messages/{id} is cached briefly, so an immediate re-fetch can still show the pre-cancellation state.

POST
/v3/messages/{id}/cancel

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

sandbox?boolean

Sandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v3/messages/8ba7b830-9dad-11d1-80b4-00c04fd430c8/cancel" \  -H "Idempotency-Key: req_abc123_retry1" \  -H "Content-Type: application/json" \  -d '{    "sandbox": false  }'
{
  "success": true,
  "data": {
    "scheduled_at": "2026-10-01T07:00:00+00:00",
    "id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "customer_id": "00000000-0000-0000-0000-000000000000",
    "contact_id": "00000000-0000-0000-0000-000000000000",
    "phone": "+14155551234",
    "phone_international": "+1 415-555-1234",
    "region_code": "US",
    "template_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "template_name": "order_confirmation",
    "template_category": null,
    "channel": "sms",
    "message_body": null,
    "status": "CANCELLED",
    "direction": "OUTBOUND",
    "created_at": "2026-09-30T11:59:00+00:00",
    "price": null,
    "active_contact_price": null,
    "events": null,
    "reason_code": null,
    "reason": null
  },
  "error": null,
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-06T09:10:22.5271005+00:00",
    "version": "v3"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_001",
    "message": "Request validation failed",
    "details": {
      "id": [
        "Invalid message ID format."
      ]
    },
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-06T09:10:22.5271045+00:00",
    "version": "v3"
  }
}
Empty
Empty
{
  "success": false,
  "data": null,
  "error": {
    "code": "RESOURCE_003",
    "message": "Message not found",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-06T09:10:22.5271394+00:00",
    "version": "v3"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "BUSINESS_006",
    "message": "Only a scheduled message can be cancelled. This message has already been released for sending, is in flight, or has finished.",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-06T09:10:22.5271397+00:00",
    "version": "v3"
  }
}
{
  "success": true,
  "error": {
    "code": "string",
    "message": "string",
    "details": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "doc_url": "string"
  },
  "meta": {
    "request_id": "string",
    "timestamp": "2019-08-24T14:15:22Z",
    "version": "string"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "INTERNAL_001",
    "message": "An unexpected error occurred while cancelling the message.",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-06T09:10:22.5271408+00:00",
    "version": "v3"
  }
}

Get message activities GET

Retrieves the activity log for a specific message. Activities track the message lifecycle including acceptance, processing, sending, delivery, and any errors.

List conversation messages GET

Retrieves a paginated list of the authenticated customer's messages across all conversations, ordered by created date (most recent first).