Sign in
SMS and MMS

Retrieve a message

Returns the SMS or MMS message identified by id, including its delivery status and content.

get/v3/messages/{id}

Path parameters

idstring required
Example:3a525ca2-6909-4c72-9399-905adf7f3a74

The unique ID of the message.

Response

Returns the message.

message_idstring required

Message ID.

message_typestring required

Message type. Possible values are sms, mms.

fromstring required

Sender ID.

tostring required

Recipient phone number.

directionstring required

Message direction. Possible values are outbound, inbound.

mccstring nullable required

Mobile country code.

mncstring nullable required

Mobile network code.

tagstring nullable required

Tag to group messages, such as for a specific campaign.

status'accepted' | 'pending' | 'sent' | 'delivered' | 'undelivered' | 'expired' | 'rejected' | 'dlr_expired' required

Current delivery status of the message. One of:

  • accepted — the message was accepted by the platform for sending.
  • pending — the message is queued and awaiting a carrier response.
  • sent — the message was handed to the carrier.
  • delivered — the carrier confirmed delivery to the handset.
  • undelivered — the carrier reported that delivery failed.
  • expired — the validity period elapsed before the message was sent.
  • rejected — the message was rejected before sending.
  • dlr_expired — no delivery receipt arrived from the carrier within the expected window.
segmentsinteger required

Number of SMS segments. Always 1 for MMS.

chargestring required

Total charge for the message in USD.

submitted_atstring required

Date and time the message was accepted in ISO 8601 format.

sent_atstring nullable required

Date and time the message was sent in ISO 8601 format. For mobile-terminated messages only.

delivered_atstring nullable required

Date and time the message was delivered in ISO 8601 format. Refers to DLR reception for mobile-terminated messages or webhook relay for mobile-originated messages.

error_messagestring nullable required

Human-readable error message.

carrier_feesstring nullable

Mobile carrier fees in USD.

Example response

{
  "message_id": "3a525ca2-6909-4c72-9399-905adf7f3a74",
  "message_type": "sms",
  "from": "15072429497",
  "to": "16419252149",
  "direction": "outbound",
  "mcc": "310",
  "mnc": "024",
  "message_body": {
    "text": "Hello, this is a test message",
    "media": null
  },
  "segments": 1,
  "status": "delivered",
  "charge": "0.01",
  "submitted_at": "2022-04-14T13:51:16.096Z",
  "sent_at": "2022-04-14T13:51:16.096Z",
  "delivered_at": "2022-04-14T13:51:16.096Z",
  "error_message": null,
  "carrier_fees": "0.0",
  "tag": "Fall sale"
}

Changes

Changed in 3 of the 50 revisions of this API.5

  • 33be779051201See the full diff
    • ○

      the endpoint scheme security bearerAuth was added to the API

      api-security-added

    This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 2e48fd9894e13See the full diff
    • ○

      api operation id Getaspecificmessage removed and replaced with sms_and_mms_messages_get

      api-operation-id-removed

    • ○

      added to the response body allOf list for the response status

      response-body-all-of-added

    • ○

      removed from the response body allOf list for the response status

      response-body-all-of-removed

    This revision also has 163 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • fabaadf195a91See the full diff
    • ○

      endpoint added

      endpoint-added