Send an SMS (v3)

Use this operation to send an SMS to an end user.

Both text and binary content are supported, as well as various enhanced message types such as WAP Push and port-directed SMS.

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

Quick facts

Method

POST with XML

Returns

XML

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-01.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 all the information required to send the SMS message, including your authentication details.

The attributes you need to use depends on where you are sending the message, and the type of message originator you are using.

Examples

This example sends a message to a US mobile phone number. This example includes the program_id attribute, which is required only for US and Canadian messages sent from a short code.

.<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="submit">
   <user agent="XML/SMS/1.0.0" />
   <account id="123-456-789-12345" password="your password" />
   <option charge_type="0" program_id="ABC" />
   <source ton="3" address="12345" />
   <destination carrier="383" ton="1" address="13135551212" />
   <message text="Hello World!" />
</request>

This example sends a message to a Mexican mobile phone number:

			
<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="submit">
   <account id="654-308-100-12345" password="mypassword"/>
   <delivery receipt_requested="true"
   url="http://mycompany.net/delivery-receipts"/>
   <option charge_type="20" />
   <source ton="1" address="5223934845"/>
   <destination ton="1" address="5225463240"/>
   <message text="Example international two-way MT"/>
</request>

You can find more examples in Example WAP Push and Binary Messages (v3) and Required Settings for Each Region (v3).

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

Required: yes

Type: string

retryOfTicketId

Use when you are retrying a previously failed MT message, to identify the original, failed MT. The value must be a valid MT ticket ID.

Required: no

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

delivery element

Use the delivery element to request a delivery receipt for the message. If this optional element is not supplied in the submit request, a delivery receipt is not returned.

Attribute

Description

receipt_requested

Whether you want OpenMarket to send a delivery receipt to your platform. Either:

  • true —You want a delivery receipt
  • false —You do not want a delivery receipt

Required: Yes

Type: Boolean

url

The URL to which you want OpenMarket to send the delivery receipt. If the request doesn't include this attribute, then we send the delivery receipt to the default URL provisioned in your account for MO delivery. The maximum length is 200 characters. The URL must begin with http://.

Required: no

Type: string

option element

Attribute

Description

type

Specify this if you are sending a WAP Push. You will also need to specify the url attribute. Set the value to WAP_PUSH.

Required: no

Type: string

url

If you are sending a WAP Push, this is the URL to sent in the message.

If the length of the URL causes the message to be greater than the maximum message length for the mobile operator, then we will reject or re-format the message as per the value of the mlc attribute.

Required: no

Type: string

charge_type

Indicates the messaging region. Either:

  • 0 — US/Canada (standard rate) SMS
  • 20 — international SMS

Required: no

Default: 0

Type: integer

program_id

Use this attribute if you are messaging via a short code in the US or Canada. This identifies the provisioned program associated with a short code for a given mobile operator. OpenMarket will confirm the exact value to specify.

Required: When short code messaging in the US and Canada.

Type: string

purpose

Use this attribute if you are messaging in India. This identifies the type of message. Options are:

  • promotional
  • transactional

For details see Required Settings for Each Region (v3).

Required: When messaging in India.

Type: string

mlc

Message length control. Determines system behavior when the message length exceeds limits set by the mobile operator.

  • 0 — Reject the MT if message text > maximum allowed for the target operator.
  • 1 — Truncate the MT if message text > maximum allowed for the target operator.
  • 2 — Automatically create multiple MTs dividing the message text at the point(s) where message text length = maximum allowed for the target operator.

Default: 0

Required: no

Type: integer

note

Use this to add data to the request that you may want available in reports, such as individual identifiers (e.g. your own transaction, ticket, or system IDs). It has no effect on the message or its delivery. The value is free-form text that is 0 to 200 characters in length.

This value appears in the SMS Detailed Data Source report. It is also returned in delivery receipts.

Required: no

Type: Latin-1 string

datacoding

Data coding used in the message. Options are:

  • 7BIT — a text message consisting of characters in the GSM 03.38 character set, plus the eight GSM extension characters: ^{}[~]|€
  • 8BIT — a binary SMS message

  • UCS2 — UTF-16 basic multilingual plane, big-endian encoding.

    Note: The basic multilingual plane does not include support for popular emojis. Please upgrade to the HTTP Global SMS API for UTF-16 support beyond the basic multilingual plane.

Required: no

Default: 7BIT

Type: string

destination element

Specifies the type of number and destination (complete mobile number) address for the SMS message.

Attribute

Description

ton

Indicates the destination address type of number, or TON. Either:

  • 1 — international phone number format
  • 0 — unknown. This is acceptable, but not recommended.

Required: yes

Type: integer

address

The mobile number to which you are sending an SMS message. Always include the country code prefix (e.g., 1 for North America).

If destination TON is 1, do not include the plus sign (+) at the start of the phone number.

If destination TON is 0, include the plus sign at the start of the phone number.

The maximum length is 20 characters.

Required: yes

Type: string

carrier

An OpenMarket-specific number for the mobile operator to which OpenMarket should route the message. OpenMarket can dynamically perform an operator lookup if your business account is enabled to do so.

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

Required: no

Type: integer

source element

Attribute

Description

ton

Indicates what type of number is set in the address attribute. For MTs this value should be one of the following:

  • 1 — International format phone number, including US and Canadian long codes, landlines and toll-free numbers.
  • 3 — Short code
  • 5 — Alphanumeric. Use only for international one-way SMS.

Required: yes

Type: integer

address

The message originator from which you want to send this message. This value can be one of:

  • International format phone number
  • Short code
  • Alphanumeric string (available only for one-way international messaging)

For a TON 1 source address, always include the country code prefix (e.g., "1" for North America). Do not include the plus sign (+) at the start of the TON 1 address.

The maximum length is 20 characters.

Required: yes

Type: ASCII character string

message element

Attribute

Description

validity_period

Specifies the period (in seconds) that OpenMarket and mobile operators will attempt to deliver the message. You can specify between 1 - 259200 seconds.

Required: no

Default: Most mobile operators will try to deliver a message for up to three days.

Type: integer

udhi

Whether a user data header (UDH) is encoded in the message. Either:

true — there is a UDH

false — there is not a UDH

Required: no

Type: Boolean

text

Text message. Use the text or data attribute to hold the message. If the length is greater than the maximum message length allowed by the mobile operator, specify behavior using the mlc attribute. The maximum length is 2680 bytes.

You can specify either plain-text or an HTML entity representation. For example:

  • "Hello World!"
  • "&#72;&#101;&#108;&#108;&#111; &#32;&#87;&#111;&#114; &#108;&#100;&#33;"

Required: no

Type: string

data

Text message. Use the text or data attribute to hold the message. If the length is greater than the maximum message length allowed by the mobile operator, specify behavior using the mlc attribute. The maximum length is 2680 bytes. You can specify either:

  • Hexadecimal-encoded text
  • Hexadecimal-encoded binary data

Required: no

Type: string

Response from OpenMarket

Accepted and rejected requests

If your request is accepted then OpenMarket sends a response similar to the below. Accepted requests include the ticket element. 

<?xml version="1.0" ?>
   <response version="3.0" protocol="wmp" type="submit">
   <error code="2" description="Message accepted." resolution="" />
   <ticket id="8310N-04298-20011-136IN" />
</response>

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

<?xml version="1.0" ?>
   <response version="3.0" protocol="wmp" type="submit">
   <error code="350" description="A destination address is required." 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. submit 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

description

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

Returned: always

resolution

This attribute is deprecated.

Returned: always

ticket element

Attribute

Description

id

The ticket ID is a unique OpenMarket identifier for the SMS message. You can use it to retrieve the status of the message, and to identify the correct delivery receipt for a message. This ID is also passed to reporting and is useful if you need to query message activity with OpenMarket Support.

Returned: Always for accepted request. Never for rejected requests.

Testing your integration

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

Troubleshooting

I didn't receive a synchronous reply back - should I retry the request?

If you receive an HTTP transaction timeout, it is still possible that we received the request. Therefore, you should decide whether you'd prefer the end user to potentially receive the message twice, or to not receive the message at all.

Response error codes

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