Query Message Status (v3)

Use this operation to obtain the status of a message. You can query for the status of a message up to five days after the message was submitted.

Note: If you're new to OpenMarket, then integrate with our Global SMS (version 4) operations.
Customers currently integrated using v3 may continue to use it, although we encourage customers to migrate to v4 in order to take advantage of new features.

Quick facts

Method

POST

Returns

POST with XML body

Available

All regions

Prerequisites

You must have SMS messaging provisioned with OpenMarket.

More information

See Overview.

Making a Request

Definition

POST smsc.openmarket.com

There are no URL parameters for this endpoint.

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

Header fields

POST /wmp HTTP/1.1
Host: smsc.openmarket.com:443/wmp
Content-Type: text/xml
Connection:  close

There are no custom header fields required. You must specify a Content-Type of text/xml in your request header.

Request body

The request body contains a ticket element, which identifies the message for which you want the status.

<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="query">
   <user agent="XML/SMS/1.0.0" />
   <account id="123-456-789-12345" password="password here" />
   <ticket id="12004-0328K-1232U-18C21" />
</request>

Request element

The request element is the outer element of the XML document.

Attribute

Description

version

Version of the API. Set to 3.0.

Required: yes

Type: string

protocol

The protocol used. Set to wmp.

Required: yes

Type: string

type

The type of request being sent. Set to query.

Required: yes

Type: string

user element

If you are using a custom user agent, define these properties to use as the user element with the following format:

[DevelopmentEnvironment]/SMS/[Version0.0.0]

Example: 

XML/SMS/1.0.0

Attribute

Description

agent

Identifies the interface used by your platform. The maximum length is 60 characters.

Required: no

Type: string

account element

Specifies your authentication details.

Attribute

Description

id

Your OpenMarket-provided account for using SMS version 3 operations.

Required: yes

Type: string

password

The password for the account.

Required: yes

Type: string

ticket element

Attribute

Description

id

The ticket ID returned by OpenMarket after you made the SMS message request.

Required: yes

Type: string

Response from OpenMarket

Accepted and rejected requests

If your request is accepted then OpenMarket sends a response similar to the below.

<?xml version="1.0" ?>
<response version="3.0" protocol="wmp" type="query">
   <error code="0" description="No Error" resolution=""/>
   <status code="0" description="Message successfully sent to carrier." resolution=""/>
</response>

If your request is rejected, then OpenMarket sends a HTTP 400-499 response. 

<?xml version="1.0" ?>
   <response version="3.0" protocol="wmp" type="query">
   <error code="307" description="The request was an ill-formed XML document" resolution="" />
</response>

The response will include the following data.

response element

Attribute

Description

version

The SMS API version. The value is always 3.0 for this operation.

Returned: always

protocol

The protocol. The value is always wmp for this operation.

Returned: always

type

Identifies that this is the response to a send SMS message request (a.k.a. query request).

Returned: always

error element

Attribute

Description

code

Number that indicates whether the request was successful or failed.

See Response and Delivery Receipt Codes for SMS Version 3 API.

Returned: always

Type: integer

description

Description for the error code. This provides some information about why a failed request may have failed.

Returned: If a description exists. Most (but not all) response codes have a description.

Type: string

resolution

This attribute is deprecated.

Returned: always

response element

This element is returned if the request was accepted.

Attribute

Description

code

The OpenMarket delivery response code defining the current state of the message. You will also see this code in your reports.

See Response and Delivery Receipt Codes for SMS Version 3 API.

Returned: always

Type: integer

description

Text description of the delivery response code.

Returned: If a description exists. Most (but not all) response codes have a description.

Type: string

Testing your integration

OpenMarket provides an option for testing your integration with the production environment. See Testing Your SMS v3 Integration.

Troubleshooting

Response error codes

For a list of response codes and delivery receipt codes, see Response and Delivery Receipt Codes for SMS Version 3 API.