Get Message Status

Use this operation to find out the current status of a message.

You can use this request up to five days after the message was submitted. After the fifth day, we return error code 711.

Quick facts

Multipart messages

If your message was split into multiple parts, then you will receive data about each part, including an individual receipt code and description. You will also receive a summary code and description. This code will help indicate the current status of the entire message:

• Code 830, "Partial message delivery failure", means that at least one of the message parts has not been successfully delivered.
• Code 831, "Awaiting complete message delivery status", means that the mobile operator has not returned a delivery receipt for one or more of the message parts. For example, you will get this code if one message part was successfully delivered but we do not have a receipt for the second part. However, if any message part fails delivery, then code 830 is returned.

Any other code means that the result for all parts of the message is the same. For example, if it is a "success" code of 0 or 4 then all parts were successfully delivered; if it is the same code to indicate a problem then all parts experienced the same problem.

Try It Out

Once you're provisioned with an OpenMarket account, you can try out the operation using cURL.

Click here to try

1. Retrieve a ticket ID

You'll need the ticket ID of a message you've sent. You can find this in the response header that OpenMarket returns for a successful MT message request.

2. Use cURL to send the message

Make a request using the following sample cURL. You'll need to:

• Replace the accountid:password with your OpenMarket account ID and password
• Replace "A1234-00000-00000-Z1234" with your own ticket ID

curl -s -D - -X GET -H "Accept: application/json" --user accountid:password https://mtstatus.openmarket.com/sms/v4/mt/A1234-00000-00000-Z1234/status

Response from OpenMarket

For successful requests, OpenMarket sends an HTTP 200 response. The header contains an X-Request-Id, while the response body contains the message status information including the ticket ID.

HTTP/1.1 200 OK
X-Request-Id: 001-3-72879E62-6586-4F77-9E7B-1E74386F0223
Content-Type: application/json;charset=UTF-8

{
   "mtStatus": {
      "ticketId": "A1234-00000-00000-Z1234",
      "code": "4",
      "description": "Message delivered",
      "deliveryDate": "2015-12-01T20:04:18.000Z",
      "note1": "My Internal ID 1234567",
      "mobileOperatorId" : 386, 
      "destination": {
         "address": "14255550100",
         "mobileOperatorId" : 386,
         "alpha2Code" : "US"
      },
         "source": {
         "ton" : 1,
         "address" : "12345520000"
      }
   }
}

Making a Request

Definition

GET https://mtstatus.openmarket.com/sms/v4/mt/<ticket ID>/status

You will need to provide the ticket ID of the message, for example:

https://mtstatus.openmarket.com/sms/v4/mt/44101-0922I-13413-21GDL/status

There are no other URL parameters for this endpoint.

This endpoint supports version Transport Layer Security (TLS) 1.2.

Header fields

You must provide your authentication details using Basic authentication in the header.

Example header

Content-Type: application/json; charset=UTF-8 
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

Request body

There is no data required in the request body.

Response from OpenMarket

Accepted requests

If your request is accepted then OpenMarket sends an HTTP 200 response with the details of the message status in the request body.

HTTP/1.1 200 OK
X-Request-Id: 001-3-72879E62-6586-4F77-9E7B-1E74386F0223
Content-Type: application/json;charset=UTF-8

{
   "mtStatus": {
      "ticketId": "03155-0331L-1439U-51SLFX",
      "code": "4",
      "description": "Message delivered",
      "deliveryDate": "2015-12-01T20:04:18.000Z",
      "note1": "Internal ID 1234567",
      "mobileOperatorId" : 386, 
      "destination": {
         "address": "14255550100",
         "mobileOperatorId" : 386,
         "alpha2Code" : "US"
      },
      "source": {
         "ton" : 1,
         "address" : "12345520000"
      }
   }
}

The following example contains the possible name-value pairs you would receive for a multipart message.

{ 
	"mtStatus": { 
		"ticketId": "03155-0331L-1439U-51SLFX", 
		"code": "831", 
		"description": "Awaiting complete message delivery status", 
		"note1": "Internal ID 1234567", 
		"totalSegments": 2, 
		"destination": { 
			"address": "32255550100", 
			"alpha2Code": "BE" 
	}, 
	"source": { 
		"ton": 5, 
		"address": "ABDCEF" 
	}, 
	"segments": [ 
		{ 
			"segmentNumber": 1, 
			"deliveryDate": "2015-10-06T22:34:17Z", 
			"code": "4", 
			"description": "Message delivered" 
		}, 
		{ 
			"segmentNumber": 2, 
			"code": "3", 
			"description": "Message accepted by mobile operator. Awaiting receipt" 
		} 
		] 
	} 
} 	

Response header

The response header will include following data.

Response body

The JSON body has a top-level object that contains the one member, mtStatus.

Multiples of the same object or object member will not occur. In the segments array, the elements share the same name-value pairs.

Status codes and descriptions

For the list of status codes and descriptions, see Delivery Receipts and Response Codes.

mtStatus object

Object that contains the message delivery status. Note that this has a subset of the same elements as the mtStatus that is returned in a delivery receipt.

This object is always included in the response.

YYYY-MM-DDTHH:MM:SSZ

2015-09-22T04:10:33Z

destination object

Object that specifies the destination of the SMS (e.g. the end user you are messaging).

source object

Object that specifies the source of the SMS (e.g. your sender details).

This object is not always included in the response.

segments array

Array that contains information about each part of a multipart message. Each part is treated as an individual message for delivery. However, on most end user's phone the parts are normally concatenated.

This array is only included if we sent the SMS in multiple parts.

YYYY-MM-DDTHH:MM:SSZ

2015-09-22T04:10:33Z

Rejected requests

If your request is rejected then the body of the response will contain a code that identifies the error. For example:

HTTP/1.1 404
Server: Apache-Coyote/1.1
X-Request-Id: 001-72-351B8F7C-59C1-420B-8A9A-59D20D93ED85
Content-Length: 82
Content-Type: application/json;charset=UTF-8
Date: Tue, 29 Sep 2015 17:54:39 GMT
Connection: close

{ 
   "error" : {
      "code":"711", 
      "description":"Ticket ID not found"
   }
}

Header fields

Response body

The response body will contain one JSON object, error.

Testing your integration

You can use the OpenMarket Customer Integration Environment (CIE) to test your integration. See Testing your integration with OpenMarket.

Troubleshooting

My request has a valid Ticket ID, but I received an error back (error code 711)

You can query the status of a message request for up to five days. After this, we will return error code 711. If for some reason you need to review what happened with the message, you can use the SMS Activity Search or find the final status of the request in OpenMarket Reporting.

Response error codes

If there is a problem with the request, you will receive one of these codes in the response body.

For the list of status codes and descriptions you might receive for accepted responses, see Delivery Receipts and Response Codes.

HTTP 400-499 codes

123-123-123-12345:Secure123

MTIzLTEyMy0xMjMtMTIzNDU6U2VjdXJlMTIz

Accept: application/json

Accept: application/xml

HTTP 500-599 codes