HTTP Global SMS API

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

Method

GET

Returns

XML

Available

All regions

Prerequisites

You must have SMS messaging provisioned with OpenMarket.

More information

See Overview.

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.

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 versions Transport Layer Security (TLS) 1.2 and 1.1.

Header fields

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

Example header

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

Field

Description

Authorization

Your account ID and password, separated by a colon, and then base64 encoded. Your account ID and password are case-sensitive. For help with Basic authentication see Authenticating with OpenMarket.

Required: always

Content-Type

Specify application/xml for this request.

Required: always

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/xml;charset=UTF-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mtStatus ticketId="01111-12013-1504Y-18K6Q" deliveryDate="2015-12-01T20:04:18.000Z" code="4" description="Message delivered" mobileOperatorId="383" note1="My Internal ID or text 1" xmlns="http://sms.openmarket.com/v4/mt">
   <destination mobileOperatorId="383" alpha2Code="US" address="14255550100"/>
   <source address="12345" ton="3"/>
</mtStatus>

The following example contains the possible elements and attributes you would receive for a multipart message.

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mtStatus ticketId="01111-12013-1504Z-19BLAH" totalSegments="2" note1="My Internal ID or text 1" mobileOperatorId="383" code="830" description="Partial message delivery failure" xmlns="http://sms.openmarket.com/v4/mt">
   <destination mobileOperatorId="383" alpha2Code="US" address="14255550100"/>
   <source address="12345" ton="3"/>
   <segments>
      <segment segmentNumber="1" deliveryDate="2015-12-01T20:04:18.000Z" code="4" description="Message delivered">
      </segment>
      <segment segmentNumber="2" code="811" description="Message expired before it reached handset" />
      </segment>
   </segments>
</mtStatus>

Response header

The response header will include following data.

Field

Description

X-Request-Id

A unique ID that identifies the specific request you made in OpenMarket's systems.

This ID is logged in our systems and is useful if you need to query the request with OpenMarket Support at a later date.

Returned: always

Type: case-insensitive string up to 45 characters in length

Content-Type

Identifies that the request contains XML in the request body.

Returned: always

Response body

The XML body has a top-level element, mtStatus.

The segment element, which is a child of the segments element, can occur multiple times. This is the only element that can occur multiple times.

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

mtStatus element

Element 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 element is always included in the response.

Attribute

Description

ticketId

The ticket ID that identifies the SMS message in OpenMarket requests and reporting.

Returned: always

Type: string

deliveryDate

The time and date that OpenMarket received a delivery receipt back from the mobile operator. This is returned with most delivery receipts or status requests (not just "Message delivered" receipts).

If your message was split into multiple parts, then deliveryDate is an attribute of the segment element and is not included as an attribute of the mtStatus element.

The date string is in the following form. Time zone is UTC:

YYYY-MM-DDTHH:MM:SSZ

Example:

2015-09-22T04:10:33Z

Returned: when known

Type: string

code

Code identifying the current delivery status for the message. See Delivery Receipts and Response Codes.

If your message is multipart, then this code is a summary of the entire message status.

Returned: always

Type: string (although the code is always a number)

description

Description of the current delivery status for the message.

If your message is multipart, then this description is a summary of the entire message status.

Returned: not always returned

Type: string

note1

Returned only if you included note1 in the MT request. This is the value you sent.

Returned: not always returned

Type: string, up to 200 characters in length

note2

Returned only if you included note2 in the MT request. This is the value you sent.

Returned: not always returned

Type: string, up to 200 characters in length

mobileOperatorId

This is decommissioned but still included for backwards compatibility. See instead the mobileOperatorId attribute that is part of the destination element.

Returned: not always returned

Type: integer

totalSegments

You will receive totalSegments and the segments elements if the message was split into multiple parts.

The value of totalSegments is the total number of parts into which OpenMarket split the message. The value will be a number from 2 or higher.

See Single and Multipart Messages..

Returned: for multipart messages only

Type: integer

xmlns

The XML namespace.

Returned: always

Type: string

destination element

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

Attribute

Description

address

The destination address specified in the MT message. This will be between 5 to 20 characters.

Returned: always

Type: string

mobileOperatorId

A numeric ID representing the mobile operator as known by OpenMarket; e.g., 383 for AT&T in the US.

For a list of the valid IDs, see Mobile Operator IDs.

Returned: not always returned

Type: integer

alpha2code

The country ID (based on the calling prefix) of the destination address. This is the 2-character ISO alphanumeric country code.

Returned: not always returned

Type: string

source element

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

This element is not always included in the response.

Attribute

Description

ton

The type of message originator, one of:

  • 1 — phone number starting with the country code
  • 3 — national short code
  • 5 — alphanumeric

Returned: always

Type: integer

address

The source address submitted in the SMS message. The value will be an ASCII character string between 1 to 20 characters long.

Returned: always

Type: string

segments and segment elements

Elements 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.

The segments and segment elements are only included if we sent the SMS in multiple parts. The segment element will occur multiple times — one for each message part.

There are no attributes for the segments element.

The segment element has the following attributes: segmentNumber, deliveryDate, code, description.

Attribute

Description

segmentNumber

Identifies the message part. The numbering begins at "1".

Returned: always

Type: integer

deliveryDate

The time and date that OpenMarket received a delivery receipt back from the mobile operator.

This is returned with most delivery receipts or status requests (not just "Message delivered" receipts).

The date string is in the following form. Time zone is UTC:

YYYY-MM-DDTHH:MM:SSZ

Example:

2015-09-22T04:10:33Z

Returned: not always returned

Type: string

code

Code identifying the current delivery status for the message. See Delivery Receipts and Response Codes.

Returned: always

Type: string

description

Description of the current delivery status for the message.

Returned: not always returned

Type: string

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/xml; charset=UTF-8
Date: Tue, 29 Sep 2015 17:54:39 GMT
Connecion: close

<?xml version="1.0"? encoding="UTF-8" standalone="yes"?>
<error code="711" description="Ticket ID not found" xmlns="http://sms.opemarket.com/v4/mt" />

Header fields

Field

Description

X-Request-Id

A unique ID that identifies the specific request you made in OpenMarket's systems.

This ID is logged in our systems and is useful if you need to query the request with OpenMarket Support at a later date.

Returned: always

Type: case-insensitive string up to 45 characters in length

Response body

The response body will contain one element, error.

JSON 

Description

code

Code defining the reason for the outcome of the request. For a list of the codes, see Response error codes below.

Returned: always

Type: string

description

Description of the error.

Returned: always

Type: string

xmlns

The XML namespace.

Returned: always

Type: string

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

OpenMarket error code

Error description

Notes

420

Invalid account ID or account password

The authentication details you sent in the requests do not match, or do not exist. Check that your account ID and password are base 64-encoded, and have a colon between them; e.g.:

123-123-123-12345:Secure123

Encodes to:

MTIzLTEyMy0xMjMtMTIzNDU6U2VjdXJlMTIz

431

Account not provisioned for SMS

We recognized your account, but it is not provisioned for SMS messaging.

Talk to your OpenMarket account manager to provision SMS messaging.

432

Account blocked for SMS

Your OpenMarket account is blocked from using this operation.

Talk to your OpenMarket account manager for more information.

540

Invalid request -HTTP accept header must specify xml or json

You must include an "accept" header in your request identifying whether you want the response in JSON or XML, e.g.:

Accept: application/json

Or:

Accept: application/xml

711

Ticket ID not found

Your request included a ticket ID that:

  • Does not exist
  • Is for a message request that occurred more than 5 days ago
  • The account does not have the right to access

This error may also occur if the URL is malformed.

HTTP 500-599 codes

OpenMarket error code

Error description

Notes

1000

Temporary error processing request

This error is returned when OpenMarket is temporarily unable to process requests. Retry your request in intervals of 10 seconds or more, and contact OpenMarket Support if you continue to receive this error.

1010

Temporary system error

This error is returned when OpenMarket is temporarily unable to process requests. Retry your request in intervals of 10 seconds or more, and contact OpenMarket Support if you continue to receive this error.