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.

Request

Path Parameters

id uuidrequired

The id of the message

Responses

200: Successful response with details about a message.

application/json

• Schema
• Example (from schema)

Schema

data

object

record_type string

Possible values: [message]

Identifies the type of the resource.

direction string

Possible values: [outbound]

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

id uuid

Identifies the type of resource.

type string

Possible values: [SMS, MMS]

The type of message.

messaging_profile_id string

Unique identifier for a messaging profile.

organization_id uuid

The id of the organization the messaging profile belongs to.

from

object

phone_number address

Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).

carrier string

The carrier of the receiver.

line_type string

Possible values: [Wireline, Wireless, VoWiFi, VoIP, Pre-Paid Wireless, ``]

The line-type of the receiver.

to

object[]

Array [

phone_number address

Receiving address (+E.164 formatted phone number or short code).

status string

Possible values: [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 string

Possible values: [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

subject stringnullable

Subject of multimedia message

media

object[]

Array [

url url

The url of the media requested to be sent.

content_type mime-typenullable

The MIME type of the requested media.

sha256 stringnullable

The SHA256 hash of the requested media.

size integernullable

The size of the requested media.

]

webhook_url urlnullable

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

webhook_failover_url urlnullable

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

Possible values: >= 1 and <= 10

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

tags string[]

Tags associated with the resource.

cost

object

nullable

amount decimal

The amount deducted from your account.

currency iso4217

The ISO 4217 currency identifier.

received_at date-time

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

sent_at date-time

ISO 8601 formatted date indicating when the message was sent.

completed_at date-time

ISO 8601 formatted date indicating when the message was finalized.

valid_until date-timenullable

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

Error[]

These errors may point at addressees when referring to unsuccessful/unconfirmed delivery statuses.

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta object

]

These errors may point at addressees when referring to unsuccessful/unconfirmed delivery statuses.

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "40385f64-5717-4562-b3fc-2c963f66afa6",
    "type": "MMS",
    "messaging_profile_id": "4000eba1-a0c0-4563-9925-b25e842a7cb6",
    "organization_id": "b448f9cc-a842-4784-98e9-03c1a5872950",
    "from": {
      "phone_number": "+18445550001",
      "carrier": "TELNYX LLC",
      "line_type": "VoIP"
    },
    "to": [
      {
        "phone_number": "+18665550001",
        "status": "queued",
        "carrier": "T-MOBILE USA, INC.",
        "line_type": "Wireless"
      }
    ],
    "text": "Hello, World!",
    "subject": "From Telnyx!",
    "media": [
      {
        "url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png",
        "content_type": null,
        "sha256": null,
        "size": null
      }
    ],
    "webhook_url": "https://www.example.com/hooks",
    "webhook_failover_url": "https://backup.example.com/hooks",
    "encoding": "GSM-7",
    "parts": 1,
    "tags": [
      "Greetings"
    ],
    "cost": null,
    "received_at": "2019-01-23T18:10:02.574Z",
    "sent_at": null,
    "completed_at": null,
    "valid_until": null,
    "errors": []
  }
}

default: Unexpected error

application/json

• Schema
• Example (from schema)

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta object

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

Loading...