GET /messaging/v1/sms/messages/{messageKey}

Retrieves the send status for an SMS message.

Requests to this endpoint are rate limited. To monitor message statuses in real time, subscribe to transactional send events using the Event Notification Service.

URL Parameters

Name	Type	Description
`messageKey`	string	Required. The unique identifier for the message.

note: When you send a message, you must provide a messageKey that’s unique among all of the keys used in your business unit over the last 2 days.

You can use this GET request to retrieve statuses for messages that are up to 3 days old. If more than one message was sent using the same message key, the API returns the status of the message that was sent most recently.

For real-time tracking of message statuses and other events, we recommend that you subscribe to transactional send events using Event Notification Service.

Responses

Status	Name	Type	Description
200			OK
	requestId	string	The unique identifier of the request.
	eventCategoryType	string	The status of the message. A status of `SMSSent` indicates that the SMS was sent to the SMS provider. `SMSNotSent` indicates that the message wasn’t sent and includes the reason. `SMSQueued` indicates that the message hasn’t yet been processed for sending.
	timestamp	string	The time the event occurred in Central Standard Time. Daylight saving time (DST) isn’t applied.
	messageKey	string	A unique identifier to track the status of the message.
	compositeId	string	An internal ID. If you contact Salesforce Support to troubleshoot SMS delivery issues, provide this ID.
	contactKey	string	The unique Marketing Cloud Engagement identifier for the subscriber.
	to	string	The recipient's mobile number.

Usage

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET /messaging/v1/sms/messages/MESSAGE_KEY
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

The response includes an ID for the request. The eventCategoryType property indicates whether the message was sent to the outbound SMS service for delivery. If the message was sent, this property has a value of TransactionalSendEvents.SMSSent.

HTTP/1.1 200 OK
{
  "requestId": "77431635-1b6b-44db-a16d-420361a43dc1",
  "eventCategoryType": "TransactionalSendEvents.SMSSent",
  "timestamp": "2018-08-03T13:41:18.55",
  "compositeId": "1F3631D4-5497-E811-80E4-1402EC6B9540.214435.228431.1.231481617",
  "info": {
    "messageKey": "bcX0qaEp0USGciEnUJTW0w",
    "contactKey": "Astro25",
  }
}

If the message is queued for processing, the eventCategoryType property has a value of TransactionalSendEvents.SMSQueued.

HTTP/1.1 200 OK
{
  "requestId": "fcdbb2f9-438b-4d52-a380-2eade2f46396",
  "eventCategoryType": "TransactionalSendEvents.SMSQueued",
  "timestamp": "2018-08-16T10:44:41.2196"
}

If the message wasn't sent, the eventCategoryType property has a value of TransactionalSendEvents.SMSNotSent. The statusMessage property in the info object provides the reason that the message wasn't sent.

HTTP/1.1 200 OK
{
  "requestId": "30486456-ed41-46ba-96eb-06c4ff3b95d9",
  "eventCategoryType": "TransactionalSendEvents.SMSNotSent",
  "timestamp": "2018-07-24T06:26:58.463",
  "compositeId": "56941A9F-3A8F-E811-80E0-1402EC6B9529.4647028.622338.1.318768528",
  "info": {
    "messageKey": "9a-zUvWf3UKxLpwwIrqTmQ",
    "contactKey": "ec25a8c8-6d4e-42f0-84c3-4ea23564cbe5",
    "statusCode": 16,
    "statusMessage": "InvalidAttributeValue"
  }
}