HTTP Global SMS API

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

Try It Out

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

Click here to try

1. Create a text file for the POST body

Create a text file called send-sms.txt and copy in the example below. You'll need to change the example phone number "12515550145" to one that you can receive messages on. Make sure that you include the country code; e.g. so that the number is in international format. Don't add a "+" character.

{
   "mobileTerminate" : {
      "message" : {
         "content" : "Hello",
         "type" : "text"
      },
      "destination" : {
         "address" : "12515550145"
      }
   }
}

2. Use cURL to send the message

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

Ensure you're in the same folder/directory as the text file
Replace the accountid:password with your OpenMarket account ID and password

curl -s -D - -X POST  -H "Content-Type: application/json" --user accountid:password --data-binary @send-sms.txt https://smsc.openmarket.com/sms/v4/mt

In the cURL, the "-s -D -" prints the HTTP response code, headers and response body to screen. For additional information useful when troubleshooting, replace "-s -D -" with "-v".

Response back from OpenMarket

For successful requests, OpenMarket returns an HTTP 202 response.

HTTP/1.1 202 Accepted
Content-Length: 0
Location: https://smsc.openmarket.com/sms/v4/mt/03155-0331L-1439U-51SLFX
Content-Type: application/json;charset=UTF-8
X-Request-Id: BAC=DE1396F5-C67B-46CF-A488-DBECEB8164D0
Server: Jetty(8.1.14.v20131031)

The location includes a ticket ID (in the example: 03155-0331L-1439U-51SLFX). This identifies the SMS message in reports, delivery receipts and with OpenMarket Support. The response also contains an X-Request-Id. This identifies an individual request.

Making a Request

Definition

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

There are no 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

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 base64 encoded. Your account ID and password are case-sensitive. For help with Basic authentication see Authenticate with OpenMarket.
Content-Type	Specify application/json for this request.

Request body

The request body contains the details for sending the message.

When to add 'interaction' to your request

One of the optional values you can include in your Send SMS requests is interaction. This identifies whether you are using one-way or two-way messaging.

If you supply the source address in the request, you don't usually need to include a value for interaction. We determine it based on the source address. However, if you're using automated originator selection to determine the originator, you may want to include a value for interaction. Also note that you do not need to specify interaction if you are messaging in the US or Canada because all messaging is considered two-way. If you do include it, we ignore it.

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 any non-India messaging, this field is ignored. See Sending to India for more information. Options are: true — The message is promotional false — The message is transactional Required: no Default: false Type: Boolean

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 any non-India messaging, this field is ignored. See Sending to India for more information. Options are:

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

Required: no

Default: false

Type: Boolean

options object

Object containing optional message settings.

Member	Description
programId	This identifies a pre-provisioned program that's linked to the short code you are using. OpenMarket will provide you with the value to use for programId. It is typically 1-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 report. 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 report. 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

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 Automated Originator Selection.

Note: A source object is incompatible with using the campaignId. If you try to send a requesting using both the campaignId and a source object, the message will fail to send.

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

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 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 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 Character encoding. 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 1 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 reject 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 See 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

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: https://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.: https://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

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

https://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

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

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 integration with OpenMarket.

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.

OpenMarket and HTTP API response error codes

This table describes OpenMarket response codes and corresponding HTTP response codes.

OpenMarket error code	HTTP status code	Error description	Notes
352	400	Invalid request - destination address country code is not recognized.	OpenMarket does not recognize the address country code passed in the request. Check that you are using the correct code.
420	401	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	403	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	403	Account blocked for SMS	Your OpenMarket account is blocked from sending SMS messages. Talk to your OpenMarket account manager for more information.
540	400	Invalid request - mobileOperatorId value is invalid	The mobileOperatorId you specified had a non-numeric character.
540	400	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	400	Invalid request - destination address is required	Your request is missing destination address.
540	400	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	400	Invalid request - message content exceeds 2680 bytes	You specified a value for content that is more than the maximum value of 2680 bytes.
540	400	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	400	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	400	Invalid request - promotional value is invalid	You included promotional in your request. The value for this must be either true or false.
540	400	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	400	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 specified a ton of 1 or 3, and your source address is an alphanumeric string (or contains an extra character, such as a "+" sign) Your source address is greater than the maximum of 20 characters
540	400	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	400	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	400	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	400	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	400	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	400	Invalid request - message is required	Your request is missing the message object/element.
540	400	Invalid request - note1 value is invalid	You specified a value for note1 that is more than the maximum value of 200 characters.
540	400	Invalid request - note2 value is invalid	You specified a value for note2 that is more than the maximum value of 200 characters.
540	400	Invalid request - programId value is invalid	You specified a value for programId that is longer than the 50 characters (the maximum character length).
540	400	Invalid request - flash value is invalid	The value for flash can only be either true or false.
540	400	Invalid request - udh value is invalid	The value for udh can only be either true or false.
540	400	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	400	Invalid request - receiptRequested value is invalid	You specified a value for receiptRequested that is not one of the valid options.
540	400	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 example, you must include http:// or https:// in the URL, or gGreater than the maximum of 2048 characters.
540	400	Invalid request - interaction value is invalid	You specified a value for interaction that is not one of the valid options.
592	403	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 CA, 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
594	400	Invalid campaign ID	Returned only for branded message requests. The campaignId in the request is either not configured in our system or is inactive. Contact your OpenMarket account manager for help.
1000	5xx	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	5xx	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.