---
title: "Retrieve a message"
method: GET
path: "/messages/{id}"
tags: ["Messages"]
---

# Retrieve a message

`GET /messages/{id}`

Note: This API endpoint can only retrieve messages that are no older than 10 days since their creation. If you require messages older than this, please generate an [MDR report.](https://developers.telnyx.com/api-reference/mdr-usage-reports/create-mdr-usage-report)

## Path parameters

- `id` string, uuid, required

## Response `200`

Successful response with details of a message.

- object
  - `data` union
    - OutboundMessagePayload
      - `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` 'queued' | 'sending' | 'sent' | '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` 'queued' | 'sending' | 'sent' | 'delivered' | 'sending_failed' | 'delivery_failed' | 'delivery_unconfirmed'
        - `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` MessagingError[] — 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.
      - `wait_seconds` number, float, nullable — Seconds the message is queued due to rate limiting before being sent to the carrier. Represents the maximum wait across all applicable rate limits (account, carrier, campaign). 0.0 = no queuing delay.
    - InboundMessagePayload
      - `record_type` 'message' — Identifies the type of the resource.
      - `direction` 'inbound' — 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. This value can be either 'sms' or 'mms'.
      - `messaging_profile_id` string — Unique identifier for a messaging profile.
      - `organization_id` string — Unique identifier for a messaging profile.
      - `to` object[]
        - `phone_number` string — Receiving address (+E.164 formatted phone number or short code).
        - `status` 'queued' | 'sending' | 'sent' | 'delivered' | 'sending_failed' | 'delivery_failed' | 'delivery_unconfirmed' | 'webhook_delivered'
        - `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` 'queued' | 'sending' | 'sent' | 'delivered' | 'sending_failed' | 'delivery_failed' | 'delivery_unconfirmed'
        - `carrier` string — The carrier of the receiver.
        - `line_type` 'Wireline' | 'Wireless' | 'VoWiFi' | 'VoIP' | 'Pre-Paid Wireless' | '' — The line-type of the receiver.
      - `from` object
        - `phone_number` string — Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).
        - `status` 'received' | 'delivered'
        - `carrier` string — The carrier of the sender.
        - `line_type` 'Wireline' | 'Wireless' | 'VoWiFi' | 'VoIP' | 'Pre-Paid Wireless' | '' — The line-type of the sender.
      - `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 — Message subject.
      - `media` object[]
        - `url` string, url — The url of the media requested to be sent.
        - `content_type` string — The MIME type of the requested media.
        - `size` integer — The size of the requested media.
        - `hash_sha256` string — The SHA256 hash 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 — Not used for inbound messages.
      - `completed_at` string, date-time, nullable — Not used for inbound messages.
      - `valid_until` string, date-time, nullable — Not used for inbound messages.
      - `errors` MessagingError[] — 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

## Other responses

- `4XX` — Unexpected error

---

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