---
title: "Cancel a scheduled message"
method: DELETE
path: "/messages/{id}"
tags: ["Messages"]
---

# Cancel a scheduled message

`DELETE /messages/{id}`

Cancel a scheduled message that has not yet been sent. Only messages with `status=scheduled` and `send_at` more than a minute from now can be cancelled.

## Path parameters

- `id` string, uuid, required

## Response `200`

Successful response

- MessagingOutboundMessagePayloadCancelled
  - `record_type` 'message' — Identifies the type of the resource.
  - `direction` 'outbound' — The direction of the message. Inbound messages are sent to you whereas outbound messages are sent from you.
  - `id` string, uuid — Identifies the type of resource.
  - `type` 'SMS' | 'MMS' — The type of message.
  - `messaging_profile_id` string — Unique identifier for a messaging profile.
  - `organization_id` string, uuid — The id of the organization the messaging profile belongs to.
  - `from` object
    - `phone_number` string — Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).
    - `carrier` string — The carrier of the receiver.
    - `line_type` 'Wireline' | 'Wireless' | 'VoWiFi' | 'VoIP' | 'Pre-Paid Wireless' | '' — The line-type of the receiver.
  - `to` object[]
    - `phone_number` string — Receiving address (+E.164 formatted phone number or short code).
    - `status` 'scheduled' | 'queued' | 'sending' | 'sent' | 'cancelled' | 'expired' | 'sending_failed' | 'delivery_unconfirmed' | 'delivered' | 'delivery_failed' — The delivery status of the message.
    - `carrier` string — The carrier of the receiver.
    - `line_type` 'Wireline' | 'Wireless' | 'VoWiFi' | 'VoIP' | 'Pre-Paid Wireless' | '' — The line-type of the receiver.
  - `cc` object[]
    - `phone_number` string — Receiving address (+E.164 formatted phone number or short code).
    - `status` 'scheduled' | 'queued' | 'sending' | 'sent' | 'cancelled' | 'expired' | 'sending_failed' | 'delivery_unconfirmed' | 'delivered' | 'delivery_failed' — The delivery status of the message.
    - `carrier` string — The carrier of the receiver.
    - `line_type` 'Wireline' | 'Wireless' | 'VoWiFi' | 'VoIP' | 'Pre-Paid Wireless' | '' — The line-type of the receiver.
  - `text` string — Message body (i.e., content) as a non-empty string. **Required for SMS**
  - `num_chars` integer — The number of characters in the message text
  - `subject` string, nullable — Subject of multimedia message
  - `media` object[]
    - `url` string, url — The url of the media requested to be sent.
    - `content_type` string, nullable — The MIME type of the requested media.
    - `sha256` string, nullable — The SHA256 hash of the requested media.
    - `size` integer, nullable — The size of the requested media.
  - `webhook_url` string, url, nullable — The URL where webhooks related to this message will be sent.
  - `webhook_failover_url` string, url, nullable — The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.
  - `encoding` string — Encoding scheme used for the message body.
  - `parts` integer — Number of parts into which the message's body must be split.
  - `tags` string[] — Tags associated with the resource.
  - `cost` object, nullable
    - `amount` string — The amount deducted from your account.
    - `currency` string — The ISO 4217 currency identifier.
  - `cost_breakdown` object, nullable — Detailed breakdown of the message cost components.
    - `carrier_fee` object
      - `amount` string — The carrier fee amount.
      - `currency` string — The ISO 4217 currency identifier.
    - `rate` object
      - `amount` string — The rate amount applied.
      - `currency` string — The ISO 4217 currency identifier.
  - `tcr_campaign_id` string, nullable — The Campaign Registry (TCR) campaign ID associated with the message.
  - `tcr_campaign_billable` boolean — Indicates whether the TCR campaign is billable.
  - `tcr_campaign_registered` string, nullable — The registration status of the TCR campaign.
  - `received_at` string, date-time — ISO 8601 formatted date indicating when the message request was received.
  - `sent_at` string, date-time, nullable — ISO 8601 formatted date indicating when the message was sent.
  - `completed_at` string, date-time, nullable — ISO 8601 formatted date indicating when the message was finalized.
  - `valid_until` string, date-time, nullable — Message must be out of the queue by this time or else it will be discarded and marked as 'sending_failed'. Once the message moves out of the queue, this field will be nulled
  - `errors` MessagingError0b38e7044b[] — These errors may point at addressees when referring to unsuccessful/unconfirmed delivery statuses.
    - `code` string, required
    - `title` string, required
    - `detail` string
    - `source` object
      - `pointer` string, json-pointer — JSON pointer (RFC6901) to the offending entity.
      - `parameter` string — Indicates which query parameter caused the error.
    - `meta` object
  - `smart_encoding_applied` boolean — Indicates whether smart encoding was applied to this message. When `true`, one or more Unicode characters were automatically replaced with GSM-7 equivalents to reduce segment count and cost. The original message text is preserved in webhooks.

## Other responses

- `403` — Forbidden
- `404` — Not found.
- `4XX` — Unexpected error

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/versions/8f5f4e537994/schema)