Sign in

v52

OpenAPI 3.1.0raw.githubusercontent.com2026-07-311,1941,9384.1 MB
Messages

Cancel a scheduled message

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.

delete/messages/{id}

Path parameters

idstring uuid required

The id of the message to cancel

Response

Successful response

completed_atstring date-time nullable

ISO 8601 formatted date indicating when the message was finalized.

direction'outbound'

The direction of the message. Inbound messages are sent to you whereas outbound messages are sent from you.

encodingstring

Encoding scheme used for the message body.

idstring uuid

Identifies the type of resource.

messaging_profile_idstring

Unique identifier for a messaging profile.

num_charsinteger

The number of characters in the message text

organization_idstring uuid

The id of the organization the messaging profile belongs to.

partsinteger

Number of parts into which the message's body must be split.

received_atstring date-time

ISO 8601 formatted date indicating when the message request was received.

record_type'message'

Identifies the type of the resource.

sent_atstring date-time nullable

ISO 8601 formatted date indicating when the message was sent.

smart_encoding_appliedboolean

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.

subjectstring nullable

Subject of multimedia message

tagsstring[]

Tags associated with the resource.

tcr_campaign_billableboolean

Indicates whether the TCR campaign is billable.

tcr_campaign_idstring nullable

The Campaign Registry (TCR) campaign ID associated with the message.

tcr_campaign_registeredstring nullable

The registration status of the TCR campaign.

textstring

Message body (i.e., content) as a non-empty string.

Required for SMS

type'SMS' | 'MMS'

The type of message.

valid_untilstring 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

webhook_failover_urlstring url nullable

The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.

webhook_urlstring url nullable

The URL where webhooks related to this message will be sent.

Example response

{
  "cc": [],
  "completed_at": null,
  "cost": {
    "amount": "0.0",
    "currency": "USD"
  },
  "cost_breakdown": null,
  "direction": "outbound",
  "encoding": "GSM-7",
  "errors": [],
  "from": {
    "carrier": "TELNYX LLC",
    "line_type": "VoIP",
    "phone_number": "+18445550001"
  },
  "id": "40385f64-5717-4562-b3fc-2c963f66afa6",
  "media": [],
  "messaging_profile_id": "4000eba1-a0c0-4563-9925-b25e842a7cb6",
  "num_chars": 13,
  "organization_id": "b448f9cc-a842-4784-98e9-03c1a5872950",
  "parts": 1,
  "received_at": "2019-01-23T18:10:02.574Z",
  "record_type": "message",
  "sent_at": null,
  "subject": "From Telnyx!",
  "tags": [
    "Greetings"
  ],
  "tcr_campaign_billable": true,
  "tcr_campaign_id": "TCPA3X7",
  "tcr_campaign_registered": "REGISTERED",
  "text": "Hello, World!",
  "to": [
    {
      "carrier": "T-MOBILE USA, INC.",
      "line_type": "Wireless",
      "phone_number": "+18665550001",
      "status": "cancelled"
    }
  ],
  "type": "SMS",
  "valid_until": null,
  "webhook_failover_url": "https://backup.example.com/hooks",
  "webhook_url": "https://www.example.com/hooks"
}