Skip to main content

Retrieve message details

GET 
/messages/:sms_id

Retrieves an MDR (Message Detail Record).

An MDR describes a specific message request - both the active/pending and completed request. We store the most recent version of its MDR.

Related:

  • Messaging Overview: Looking up Messaging Detail Records discusses MDRs in far more detail
  • Reports (MDR) API endpoints

Request ​

Path Parameters

    sms_id stringrequired

    ID of message [request]

Responses ​

200: Current MDR

Schema

    sms_id uuidrequired

    ID of message (Telnyx-specific)

    sms_gw_id uuid

    ID of message used off-network (Unlikely to be used, unless contacting Telnyx Support)

    user_id uuid

    ID of user who owns the sending phone number (empty string when not applicable)

    profile_id uuid

    ID of messaging profile to which the sending phone number is assigned

    body

    object

    required

    coding integerrequired

    Possible values: [0, 3, 8]

    Default value: 3

    Encoding scheme used for the message body

    num_chars integerrequired

    Number of characters in the decoded byte payload

    text stringrequired

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

    num_bytes integerrequired

    Number of bytes in the message payload

    bytes_hash stringrequired

    SHA256 hash of the raw bytes sent over SMPP

    text_hash stringrequired

    SHA256 hash of the message encoded in UTF-8

    parts integerrequired

    Default value: 1

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

    status stringrequired

    Possible values: [sending, gw_timeout, sent, dlr_timeout, delivered, failed]

    State of the POST /messages request

    delivery_status string

    NOTE: 'status' refers to the state of the message [request].

    'delivery_status' is used to pass back to you miscellaneous information, often relating to the delivery status webhook.

    created integer

    Created at time (Unix time in milliseconds)

    updated integer

    Update at time (Unix time in milliseconds)

    date_created dateTime

    Created at date and time (ISO 8601 in UTC)

    date_updated dateTime

    Updated at date and time (ISO 8601 in UTC)

    from stringrequired

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

    to stringrequired

    Receiving address (+E.164 formatted phone number)

    direction string

    Possible values: [inbound, outbound]

    Whether the message was inbound or outbound

    on_net boolean

    Whether the message stayed within the Telnyx network

    cost string

    Amount

    currency string

    Possible values: [USD]

    Currency of the value of 'cost'

    type string

    Possible values: [SMS = text message]

    Default value: SMS

    Type of messaging service

Request samples

curl -L 'https://sms.telnyx.com/messages/:sms_id' \
-H 'Accept: application/json'

Response samples

{
  "sms_id": "c51c89d9-68ad-4db2-a471-cf622d21c40d",
  "sms_gw_id": "c51c89d9-68ad-4db2-a471-cf622d21c40d",
  "user_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  "profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
  "body": {
    "coding": 3,
    "num_chars": 6,
    "text": "Hello!",
    "num_bytes": 6,
    "bytes_hash": "string",
    "text_hash": "string",
    "parts": 1
  },
  "status": "sending",
  "delivery_status": "success",
  "created": 1522097596060,
  "updated": 1522097596753,
  "date_created": "2018-03-26T20:53:16.060000",
  "date_updated": "2018-03-26T20:53:16.753000",
  "from": "+13125550001",
  "to": "+13125550001",
  "direction": "inbound",
  "on_net": true,
  "cost": "0.00450",
  "currency": "USD",
  "type": "SMS"
}