Retrieve a message

Path Parameters

• idstringrequired

Responses

• 200Message

  The message

• 401Error

  Missing, malformed, or revoked API key

• 402Error

  Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

• 404Error

  Not found

• 429Error

  Rate limit or quota exceeded

Response Fields

• idstring

  Example: msg_a1B2c3D4e5F6g7H8.

• objectmessage
• tostring

  Example: +15005550006.

• fromstring

  Example: +15005550100.

• bodystring
• directionoutbound, inbound
• statusqueued, sent, delivered, failed, blocked, received

  blocked: refused by one of our checks before any carrier saw it (opt-out, quiet hours, unregistered sender, content, allowance, spend limit, credits). Final, never charged; failure says why. failed: accepted, then not delivered.

• testboolean
• simulatedboolean

  True when nothing was handed to a carrier: every test-key message except one sent to your own verified phone. Always false on live messages. A simulated message still reaches delivered.

• noticestring

  Only on the response to POST /messages. Present when a test-key send to a real-looking number was simulated: says nothing was sent and how to send for real.

• schedule_idstring

  The recurring schedule this message is an occurrence of. Present only when set.

• tagsarray of string

  The labels sent with the message (tags on POST /messages), lowercased. Present only when set.

• categorymarketing, transactional, otp

  How the message was classified. Present when you sent one, or when it was classified as marketing.

• disclosures_addedarray of brand, opt_out

  Wording we added to a message from a number linked to a registration (what we add): brand, your business name in front of a person's first message; opt_out, " Reply STOP to opt out." on marketing that had none. body is the text as sent. Present only when we added something.

• deferredobject

  Present when the message was held for quiet hours and sent when the window opened.

• deferred.reasonquiet_hours
• deferred.held_atstring (date-time)
• redacted_atstring (date-time)

  When the message was redacted (POST /messages/{id}/redact): body is empty and media is gone. Present only then.

• linksarray of object

  Links shortened with shorten_links, in the order they appear. On the send response and GET /messages/{id} (with clicks so far); not on list pages. body is the text as sent, with the short links.

• links[].urlstring

  The link as you wrote it.

• links[].short_urlstring

  Example: https://links.example.com/Ab3dEf9h.

• links[].clicksinteger

  Opens by people. Link previews (a messaging app fetching the link to draw a preview) are not counted.

• links[].first_clicked_atstring (date-time)

  Nullable.

• links[].last_clicked_atstring (date-time)

  Nullable.

• created_atstring (date-time)
• mediaarray of string (uri)

  MMS attachments (inbound today).

• sent_bystring

  Console user or API key that composed it.

• failure_reasonstring

  The carrier's raw text for a failed send. Kept for compatibility; see failure.

• attemptsinteger

  Live sends: carrier submissions so far. More than 1 means it was retried.

• next_attempt_atstring (date-time)

  Present while queued for an automatic carrier retry.

• receipt_statusmissing

  The carrier accepted the message but sent no delivery report within 72 hours. status stays sent.

• customer_idstring

  The customer this is attributed to. Present only when set.

• timelinearray of object

  Every status transition, oldest first. Inbound messages have a single received.

• timeline[].statusaccepted, validated, queued, sent_to_carrier, carrier_accepted, retry_scheduled, delivered, failed, blocked, received
• timeline[].atstring (date-time)
• timeline[].attemptinteger

  Carrier attempt this step belongs to (from sent_to_carrier on).

• segmentsinteger

  Parts the body is split into (GSM-7: 160, then 153 each; UCS-2: 70, then 67). Example: 1.

• encodinggsm7, ucs2
• priceobject

  What this message costs, in USD: the outbound rate per segment, plus the recipient's carrier fee per segment, at cost, as its own line. Null on messages sent before prices were recorded. Nullable.

• price.totalnumber

  Example: 0.0082.

• price.currencyusd
• price.breakdownarray of object
• price.breakdown[].labelstring
• price.breakdown[].amountnumber
• destination_carrierstring

  The recipient's mobile carrier, when a cached lookup knows it. Nullable.

• failureFailure

  Null unless status is failed. Nullable.

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

• 401

  Missing, malformed, or revoked API key

• 402

  Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

• 404

  Not found

• 429

  Rate limit or quota exceeded