API Reference

Send an SMS

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

If your business involves messaging people across the globe, then you may wish to use automated originator selection to take care of setting the right source address for each country. For more information, see Using Automated Originator Selection.

Quick facts

Method

POST with JSON

Returns

JSON

Available

All regions

Prerequisites

You must have SMS messaging provisioned with OpenMarket.

More information

See SMS Messaging Overview.

Try It Out

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

Making a Request

Definition

POST https://smsc.openmarket.com:443/sms/v4/mt

There are no URL parameters for this endpoint.

This endpoint supports versions 1.0, 1.1, and 1.2 of Transport Layer Security (TLS).

Header fields

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

Example header

POST /sms/v4/mt HTTP/1.1
Host: smsc.openmarket.com
Content-Type: application/json; charset=UTF-8 
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

Field

Description

Authorization

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

Content-Type

Specify application/json for this request.

Request body

The request body contains the details for sending the message.

The following example includes most of the JSON objects and name-value pairs you can include to send a plain text message. However, note that some of these are optional and may not be relevant to your messaging.

{
   "mobileTerminate" : {
      "interaction": "two-way",
      "promotional": "false",
      "options": {
         "note1": "My Internal ID or text 1",
         "note2": "My Internal ID or text 2",
         "programId": "1234",
         "flash": "false"
      },
      "destination": {
          "address": "12125550123",
         "mobileOperatorId": 383
      },
      "source": {
         "ton": 3,
         "address": "222111"
      },
      "message": {
         "content": "This is a text message!",
         "type": "text",
         "validityPeriod": 259200,
         "mlc": "segment"
      },
      "delivery": {
         "receiptRequested": "final",
         "url": "https:my.example.com/receiver.php"
      }
   }
}

JSON properties

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

Multiples of the same object or member are not allowed.

mobileTerminate object

Member

Description

interaction

Whether this is a global one-way or two-way message. You do not need to specify interaction if you are messaging in the US or Canada (the value is ignored). Options are:

  • one-way — Uses global one-way messaging
  • two-way — Uses global two-way messaging

The values are case-sensitive.

Required: no

Default: See Automated originator selection.

Type: string

promotional

Required for India messaging only. This identifies whether the message is transactional or promotional. For more information, see Sending to India. Options are:

  • true — The message is promotional
  • false — The message is transactional

Required: no

Default: false

Type: Boolean

options object

Object that contains a variety of optional message sending options.

This object is optional.

Member

Description

programId

Required for US messaging when using a short code. The value is ignored for all other messaging.

This identifies a pre-provisioned program linked to the short code messaging service you are providing. OpenMarket will provide you with the value, which will be between 1 to 50 characters, and is not case-sensitive.

Required: no

Default: no default

Type: string

note1

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 and MAR Detailed reports. It is also returned in delivery receipts.

Required: no

Default: no default

Type: string

note2

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 and MAR Detailed reports. It is also returned in delivery receipts.

Required: no

Default: no default

Type: string

flash

Determines whether the message is sent as a flash message. Flash messages are shown immediately on an end user's mobile phone without the user taking any action, and are often not saved to the phone. We recommend avoiding sending an SMS that is both multipart and flash. Options are:

  • true — Message is sent as a flash SMS
  • false — Message is not sent as a flash SMS

This value is ignored when sending a binary message.

Required: no

Default: false

Type: Boolean

destination object

Object that contains details about the message recipient (the end user's details).

This object is required.

Member

Description

address

The phone number to which you are sending an SMS message.

This must be a phone number that includes the country code. Do not include a "+" character. For example:

  • 12125550123 (US number)
  • 447700900750 (UK number)
  • 61491570156 (Australian number)

The length must be between 5 to 20 digits.

Required: yes

Type: string

mobileOperatorId

An OpenMarket-specific number that identifies the mobile operator to which OpenMarket should route the message.

You can include mobileOperatorId when you are sending a message using a US or Canada short code, toll-free number, or landline number. It is optional as OpenMarket will perform a dynamic operator lookup if you do not supply a value. Depending on your contract with OpenMarket, you may be charged for each lookup.

Don't include mobileOperatorId when you are sending global messages, or sending using a US or Canadian virtual mobile number (VMN). OpenMarket ignores the value and performs a dynamic operator lookup for these messages. You are not charged for these lookups.

For a list of valid mobile operators IDs, see Mobile Operator IDs.

Required: no

Default: OpenMarket performs an operator lookup.

Type: integer

source object

Object that contains details about the message sender (your details).

The object is optional. If you do not include source in your request, then OpenMarket will automatically select an originator. For more information, see Using Automated Originator Selection.

Member

Description

address

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

  • Short code
  • Alphanumeric string
  • Virtual mobile number (VMN)
  • US only: a text-enabled toll-free or landline number

The value must be between 1 to 20 characters in length. Alphanumeric strings can use the characters A-Z, a-z, and 0-9. Long codes, landlines, VMNs, and toll-free numbers must include the country code. However, do not include a plus "+" character.

See also Message Originators.

Required: yes

Type: string

ton

Indicates what type of number is set in address. OpenMarket will validate the source address based on the ton value. Options are:

  • 1 — A toll-free number, long code, VMN or landline
  • 3 — A short code
  • 5 — An alphanumeric string

Required: no

Default: no default

Type: integer

message object

Object that contains details about the message you are sending.

This object is required.

Member

Description

type

Identifies what type of message you are sending (text, WAP Push, or binary). For text messages, it also identifies whether you are sending the message contents to us as plain text or hex-encoded text.

For hex-encoded text, you will also need to include the charset element in your request. For WAP Push messages, you will also need to include the url element in your request.

Options are:

  • text — Message is in UTF-8.
  • hexEncodedText — Message is hex encoded.
  • binary — Message is binary content.
  • wapPush — Message is a WAP Push.

The values are case-sensitive.

Required: yes

Type: string

content

The message sent to the end user's phone. The following applies:

  • type = text, then content must be plain text in UTF-8
  • type = wapPush, then content must be plain text in UTF-8. This text is turned into a link. You also need to include the element url to specify the link location.
  • type = hexEncodedText, then content must be hex-encoded text, and you will need to specify the character encoding using charset
  • type = binary, then content must be hexadecimal-encoded binary

Alphanumeric string that is between 1 to 2680 bytes in size.

If the content is longer than one SMS message, then it may be rejected, truncated, or segmented. The value of mlc sets this behavior. See also Single and Multipart Messages.

Required: yes

Type: string

charset

Required if the message type is set to hexEncodedText.

Identifies the character set or encoding that you have used for the text. This is valid only for hex-encoded text (otherwise the value is ignored). Options are:

  • GSM
  • Latin-1
  • UTF-8
  • UTF-16

The values are case-sensitive. See also Options for charset.

Required: no

Default: no default

Type: string

validityPeriod

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

Required: no

Default: no default. OpenMarket and the mobile operator use their standard retry strategies.

Type: number

url

Required if the message type is set to wapPush.

The URL that you want sent in the WAP Push. If the length of the URL causes the message to be greater than a single SMS, then the message may be rejected, truncated, or segmented, based on the behaviour set by the mlc member.

The value must be between 12 to 2048 characters. The URL must begin with the protocol, e.g.: https:// or http://.

Required: no

Default: no default

Type: string

mlc

Specifies what action to take if the message content is larger than a single part SMS. Options are:

  • reject — We rejects the message.
  • truncate — We send only the first part of the message that fits into a single SMS.
  • segment — We send the message as a multipart message. If this is outside the mobile operator's size limit for a multipart message, then it is rejected.

The values are case-sensitive. See also Single and Multipart Messages.

Required: no

Default: reject

Type: string

udh

Indicates whether a user data header (UDH) is encoded in the message.

This value is valid when type is either hexEncodedText or binary. For other message types the value is ignored. Options are:

  • true — There is a UDH
  • false — There is no UDH

Required: no

Default: false

Type: Boolean

delivery object

Object that identifies that you want to receive delivery receipts.

This object is optional. If this object is excluded from the request, then you will not receive delivery receipts for the message.

Member

Description

receiptRequested

Indicates that you want to receive a delivery receipt for the message. OpenMarket will send the delivery receipt when the mobile operator sends us a final delivery state.

The value is case-sensitive.

Required: yes

Type: string; only valid value is final.

url

The URL to which you want us to send delivery receipts for this message.

The value must be between 12 to 2048 characters. The URL must begin with the protocol, e.g.: https:// or http://.

Required: no

Default: We send the delivery receipt to the URL specified during your account provisioning. If there is no provisioned URL, then we do not send a delivery receipt.

Type: string

Response from OpenMarket

Accepted requests

If your request is accepted then OpenMarket sends an HTTP 202 response, with the following information in the header.

HTTP/1.1 202 Accepted
Server: Apache-Coyote/1.1
Location: http://smsc.openmarket.com/sms/v4/mt/03155-0331L-1439U-51SLFX
X-Request-Id: 001-3-72879E62-6586-4F77-9E7B-1E74386F0223
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Date: Tue, 31 Mar 2015 18:39:51 GMT
Connection: close

The response body is empty.

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

Location

The URI for the message resource. The last part of the URI path is a ticket ID; e.g.:

http://smsc.openmarket.com/sms/v4/mt/<ticket ID>

You will need the ticket ID when querying the status of an SMS 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

Type: string, maximum length of 23 characters

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 400 Bad Request
Server: Apache-Coyote/1.1
X-Request-Id: 001-1-761372B6-EE31-427E-AEB4-ED9E88CDD7A6
Content-Type: application/json;charset=UTF-8
Date: Tue, 13 Oct 2015 21:01:59 GMT
Connection: close
					
{
"error":{
   "code":"540",
   "description":"Invalid request - destination address is required"
   }
}

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 object, error.

Member

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 for rejected requests

Type: string

description

Description of the error.

Returned: always for rejected requests

Type: string

Testing your integration

You can use the OpenMarket Customer Integration Environment (CIE) to test your integration. See Testing Your SMS 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.

There are a lot of 540 error codes - what do they mean?

We use the 540 code when there is an issue with the format or syntax of your request. The code description will provide a reason. This may be because:

  • You are missing a required object.
  • The value for a JSON name-value pair is invalid; for example, it is misspelled, too long or short, is supposed to be a Boolean or number value, or includes characters not allowed in the value.

How do I know whether my request became a single-part or multipart message?

OpenMarket can't tell you in the synchronous response whether a message requires more than one part. This is because we need to check what encoding and message length the mobile operator accepts before processing the message.

Instead, the delivery receipt will tell you whether a message required more parts, and if so, how many parts the message required.

You can also check this by making a Get Message Status request.

Why did I receive an HTTP 415 status code?

This refers to the Content-Type field that is specified in the header. You must include this header in your requests. For JSON requests, set this to application/json.

We don't return a separate OpenMarket response error code in the body for this type of error.

Response error codes

These codes are returned in the response body when there was a problem with receiving the request.

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 sending SMS messages.

Talk to your OpenMarket account manager for more information.

540

Invalid request - mobileOperatorId value is invalid

The mobileOperatorId you specified had a non-numeric character.

540

Invalid request - destination address value is invalid

There is a problem with the value for destination address:

  • There is no value specified
  • The value is less than 5 characters or greater than 20 characters in length
  • The value contains a non-numeric character, like a plus sign, e.g.: "+447700900765"

You must ensure that end user's phone numbers have a country code, and don't include include any additional symbols or letters, e.g.: "447700900765" (UK number) or "12515550145" (US number).

540

Invalid request - destination address is required

Your request is missing destination address.

540

Invalid request - message content must have a value

You did not include a value for content in your request. The value must be a minimum of 1 byte.

540

Invalid request - message content exceeds 2680 bytes

You specified a value for content that is more than the maximum value of 2680 bytes.

540

Invalid request - message content value is invalid

This error occurs when the message type is hexEncodedText and we cannot interpret the message content. This may be because the value for charset is incorrect. For example, if you specify Latin-1, then you will get this error if you instead use UTF-16.

540

Invalid request - mlc value is invalid

You specified a value for mlc that is not one of the valid options. Values are case-sensitive.

540

Invalid request - promotional value is invalid

You included promotional in your request. The value for this must be either true or false.

540

Invalid request - source ton value is invalid

You specified a value that is not valid for the source ton. This must be a number, one of: 1,3 or 5.

540

Invalid request - source address value is invalid

Occurs when you have included source in your request and:

  • You did not include a source address
  • You specify a ton of 1 or 3, and your source address is an alphanumeric string (or contains an extra character like a "+" sign)
  • Your source address is greater than the maximum of 20 characters

540

Invalid request - type value is invalid

You specified a value for type that is not one of the valid options. Values are case-sensitive.

540

Invalid request - charset value is invalid

You specified a value for charset that is not one of the valid options. Values are case-sensitive.

540

Invalid request - wapPush url value is invalid

You specified that the message is type of wapPush; however, either:

  • url is missing from the request
  • The value of url is invalid (we do some basic URL validation)
  • The length is smaller than 12 characters or greater than 2048 characters

540

Invalid request - validityPeriod value is invalid

You specified a value for validityPeriod that is more than the maximum value of 259200, or you have included non-digits in the value.

540

Invalid request - invalid XML in the payload

OR

Invalid request - invalid JSON in the payload

Your request body is either missing, or we cannot parse the XML/JSON in the body.

540

Invalid request - message is required

Your request is missing the message object/element.

540

Invalid request - note1 value is invalid

You specified a value for note1 that is more than the maximum value of 200 characters.

540

Invalid request - note2 value is invalid

You specified a value for note2 that is more than the maximum value of 200 characters.

540

Invalid request - programId value is invalid

You specified a value for programId that is longer than the 50 characters (the maximum character length).

540

Invalid request - flash value is invalid

The value for flash can only be either true or false.

540

Invalid request - udh value is invalid

The value for udh can only be either true or false.

540

Invalid request - receiptRequested is required as the request includes delivery

Your request included the delivery object/element. When this is included you must also include receiptRequested.

540

Invalid request - receiptRequested value is invalid

You specified a value for receiptRequested that is not one of the valid options.

540

Invalid request - delivery url value is invalid

Inside the delivery object/element, the value for url is either: Not a correctly formatted URL. For example, you must include http:// or https:// in the URL. Greater than the maximum of 2048 characters.

540

Invalid request - interaction value is invalid

You specified a value for interaction that is not one of the valid options.

577

Account not provisioned to use SMS demo short code

Returned for US messaging only.

You have attempted to use an OpenMarket short code that is reserved for demoing US messaging.

Contact your account manager if you would like to try out US standard rate SMS using our demo short code.

Retryable: no

578

Exceeded the time limit for using SMS demo

You can use demo OpenMarket SMS messaging for a limited time only. Contact your OpenMarket account manager to extend your trial.

Retryable: no

579

Destination address not in whitelist for SMS demo

When demoing OpenMarket SMS messaging, you are limited to sending messages only to a whiltelist of mobile numbers you have told us you wish to message. The phone number you attempted to message is not on the whitelist.

Contact OpenMarket Support to add the phone number to the whitelist.

Retryable: no

580

Exceeded the max number of demo requests

You can only send a limited number of MT messages while demoing OpenMarket SMS messaging.

Contact your OpenMarket account manager if you wish to extend this limit.

Retryable: no

591

Exceeded the monthly limit on global MT messaging

You have reached the agreed MT message limit on your account for global one-way and two-way messaging.

Please contact your OpenMarket account manager if you want to discuss changing this limit.

Retryable: no

592

Account not provisioned for global one- or two-way SMS

The end user's number has a country code that is from a region of the world that you are not provisioned to reach. For example, if you exclusively message in the US or UK, you will not be provisioned for messaging end users who reside in other regions.

If you'd like extend your messaging to reach end users globally, please contact your OpenMarket account manager.

Retryable: no

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 finish processing the request. We may have sent the message on to the mobile operator. Therefore we recommend not retrying your request if you receive this error more than once, 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.