UK SMS HTTP
Broadcast an SMS
This operation enables you to send an SMS to one or more end users (up to 10,000).
Important: The information and contents displayed in these pages is for the OpenMarket's legacy UK SMS APIs. This information is relevant if only you're still using these APIs. For information on migrating from these APIs, see the API Release Notes. Please note, however, that Reporting is still done through Partner Centre, located here: https://partner.mxtelecom.com/home.
Quick facts
Method |
POST |
Returns |
Plain text. |
Prerequisites |
Available for existing customers only. |
More information |
See Overview. |
Multiple requests with the same submit ID
The submitid uniquely identifies the broadcast request and you should ensure that each new broadcast request uses a unique ID.
If the API receives two requests with the same submitid value within a 24 hour period, then it will not action the second request. Instead, it will return the results of the first submitted request. This is regardless of whether there are differences between the values or parameters of the two requests. Each time a request is submitted with the same submitid value in a 24 hour period, the 24 hour window restarts.
However, in case the same value for submitid is accidentally re-used over the lifetime of your accounts, if requests with the same submitid value are separated by more than 24 hours, then OpenMarket will consider them as separate requests.
Using the correct SMS Gateway account
To send standard rate broadcast SMS messages in the US:
- If you have an MX One account, use this account for all mobile numbers
- If you do not have an MX One account, group the numbers by mobile operator, and send each group through the correct SMS Gateway account for that operator.
To send bulk broadcast SMS messages in the UK, use your normal bulk SMS Gateway account.
Premium rate SMS Gateway accounts are linked to individual mobile operators. If you are planning on sending premium rate SMS messages using a broadcast request, you will need to group the mobile numbers by operator and send each group through the correct SMS Gateway account for that operator.
Making a Request
Definition
GET http://sms.openmarket.com/sms/v1/bulksend
GET https://sms.openmarket.com/sms/v1/bulksend
There are no URL parameters for this endpoint.
Request body
The request body contains both your authentication details and the message request details.
Use application/x-www-form-urlencoding encoding. Each parameter/value pair is separated by an "&" character, and must be URL encoded and use UTF-8.
For example, to send a plain text SMS message saying "hello" to the mobile numbers (MSISDNs) 447700900750, 447700900765 and 447700900999, send these parameters in the request:
user=MyBulkAccount&pass=MyP4S5w0rD&submitid=12345&smsto=447700900750%0A447700900765%0A447700900999&smsfrom=58870&smsmsg=hello
The "%0A" between each mobile number is a URL encoded line break.
Parameters
The following parameter tables below are split by the type of message you wish to send. The tables are:
- Generic parameters — the parameters that relate to all requests, like your authentication details. You'll still need to include parameters specific to the type of message you are sending.
- Plain text SMS, using Modified Latin-9
- Plain text SMS, using GSM 03.38
- Plain text SMS, using UCS-2 Unicode
- Binary data SMS
- WAP Push
- MMS notifications
- vCards
Parameters must be URL encoded.
Generic parameters
These parameters may be used for any request.
Parameter |
Description |
---|---|
user |
The SMS Gateway account you are sending the message through. Required: yes |
pass |
The password for the account. Required: yes |
smsto |
The mobile numbers of the message recipients in international format — for example, 447700900750. No leading "+" is required. Separate each mobile number with a line break:. For example: smsto=447700900750%0A447700900765%0A447700900999 Required: yes |
smsfrom |
Your sender details; also referred to as your message originator. This can be either a phone number (up to 16 digits) or an alphanumeric string encoded in the Modified Latin-9 character set (up to 11 characters). Required: for bulk services outside the US. This value is ignored for premium rate services (your short code is used instead) and any US messaging. In these scenarios, the originator is set for each account and cannot be changed. |
submitid | A text string up to 30 characters that uniquely identifies the broadcast request. You should ensure that each new broadcast request uses a unique ID. For example, if you were sending daily broadcasts, you could use the current date — for example, "broadcast_2014-10-01". |
report |
Whether you want a delivery report returned for the message. We recommend setting report to 7, so that you receive all possible reports.
Required: no Default: 0 |
note |
Note that will be stored in the transaction log and passed back with delivery reports. This can be up to 160 characters in length. This field is not passed to the mobile operator, and has no effect on the delivery of the message. Required: no Default: no default |
subaccount |
Sub-account to be stored in the transaction log. This can be up to 30 characters in length. OpenMarket 's Partner Centre can provide reporting based on this field. Sub-accounts do not need to be preconfigured. This field is not passed to the mobile operator, and has no effect on the delivery of the message. Required: no Default: no default |
vp |
Length of time, in seconds, that the operator will attempt to send the SMS to the end user. If the operator cannot initially reach the end user, then the standard retry strategy for the operator is used until this validity period is reached. You can specify any positive number; however, OpenMarket may need to adjust the value as some operators have minimum validity periods, or only allow specific values (such as in 30 second increments). See Overview for more information about validity periods. Required: no Default: There is no validity period set. OpenMarket and the mobile operator will use their standard retry strategies. |
billingsingleshot |
Enable single-shot billing for the message. Any non-empty value will enable single-shot billing. This parameter is only valid when sending a premium rate message in the UK, Ireland, or Australia. You can enter any value for this parameter to enable it. For example: billingsingleshot=anything See Overview for more information about single-shot billing. Required: no Default: messages are submitted as normal |
Plain text SMS, using Modified Latin-9
Add these parameters if you want to send a message using Modified Latin-9.
Use the following encoding to include a pound or euro symbol in your message:
- %A3 to create a pound sterling sign (£)
- %A4 to create a Euro sign (€)
Parameter |
Description |
---|---|
smsmsg |
The message text, encoded in the Modified Latin-9 character set. Required: yes |
bits |
The bits parameter is used to identify the type of data you are sending in the message body of the request. You only need to specify this parameter when you are sending User Data Header (UDH) information in the SMS message (with the smsudh parameter). For this type of request, bits must equal 7. Required: no Default: message does not include UDH |
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. It is not recommended to send an SMS that is both multipart and flash.
Required: no Default: 0 |
smsudh |
Enables you to add User Data Header (UDH) information. The format of UDH information is octet pairs in decimal notation — for example, 06050430393039. For this specific message request, you must also specify bits=7 if you are including UDH information in the message. If you specify the smsudh parameter, then OpenMarket will ignore the split parameter, if specified. To send a multipart message, you will need to manually split the message into separate requests and use the UDH information to concatenate the message. Required: no Default: no default |
split |
Determines whether OpenMarket treats the message as single or multiple part. The smsudh and split parameters are mutually exclusive.
Required: no Default: 0 |
Plain text SMS, using GSM 03.38
Add these parameters if you want to send a message using GSM 03.38.
Use the following encoding to include a pound or euro symbol in your message:
- %A3 to create a pound sterling sign (£)
- %A4 to create a Euro sign (€)
Parameter |
Description |
---|---|
smsia5 |
The message text, encoded in the GSM 03.38 character set. Required: yes |
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. It is not recommended to send an SMS that is both multipart and flash.
Required: no Default: 0 |
smsudh |
Enables you to add User Data Header (UDH) information. The format of UDH information is octet pairs in decimal notation,— for example, 06050430393039. If you specify the smsudh parameter, then OpenMarket will ignore the split parameter, if specified. To send a multipart message, you will need to manually split the message into separate requests and use the UDH information to concatenate the message. Required: no Default: no default |
split |
Determines whether OpenMarket treats the message as single or multiple part. The smsudh and split parameters are mutually exclusive.
Required: no Default: 0 |
Plain text SMS, using UCS-2 Unicode
Add these parameters if you want to send a message using UCS-2 16-bit characters. For example, the character 三 (the Japanese symbol for the number three) is hexadecimal encoded as 4E09. As UCS-2 Unicode is a 16-bit encoding, using it to send SMS messages reduces the maximum number of characters you can include in the message.
Parameter |
Description |
---|---|
smsucs2 |
The message text as hexadecimal encoded UCS-2. Required: yes |
smsudh |
Enables you to add User Data Header (UDH) information. The format of UDH information is octet pairs in decimal notation — for example, 06050430393039. If you specify the smsudh parameter, then OpenMarket will ignore the split parameter, if specified. To send a multipart message, you will need to manually split the message into separate requests and use the UDH information to concatenate the message. Required: no Default: no default |
split |
Determines whether OpenMarket treats the message as single or multiple part. The smsudh and split parameters are mutually exclusive.
Required: no Default: 0 |
Binary data SMS
This request type is commonly used to send binary information to a specific port or application on an end user's mobile phone.
Parameter |
Description |
---|---|
smsmsg |
The 8-bit binary content you are sending. You must hexadecimal encode the data. Required: yes |
smsudh |
The UDH information, in the format of octet pairs in decimal notation — for example, 06050430393039. Required: yes |
WAP Push
You can use this request to send, replace, or delete a WAP Push Service Indication. We support WAP 1.2 Push Service Indications; for more information about these see the WAP Service Indication Specification.
The WAP Push is uniquely identified in the mobile phone with siid=example.com-siid123. The push_siname is a description for the WAP Push that the mobile phone may display to the end user.
In the US, you must have a binary-enabled short code to use WAP Pushes.
Parameter |
Description |
---|---|
pushtype |
This identifies to OpenMarket that you are sending a WAP Push. You must set this to the number 0. Required: yes |
push_action |
This tells the mobile phone what action to take when the WAP Push arrives. We recommend setting this to 2 for WAP Push messages to URIs that you wish the end user to visit immediately. Some mobile phones may behave differently from described.
Required: yes |
push_href |
The location (URI) of the WAP Push content. This must begin with either http:// or https://. Required: yes |
push_siname |
Name of the Service Indication. This is delivered to the end user's mobile phone, and may be used by the mobile phone to identify the WAP Push to the end user. Required: yes |
push_siid |
A text string used to identify each WAP Push in a mobile phone. This parameter is required if you are deleting a WAP Push (using push_action=4). To avoid conflicts between messages from your services and other services, it is highly recommended that you create an SI ID that includes a URI you control and a unique identifier from your system (for example: www.example.org/siid/123 or 123@siid.example.org). Required: no Default: the URI specified by the push_href parameter |
push_siexpires |
This sets an expiry date and time for the WAP Push. When it reaches this date, the mobile phone should either delete the WAP Push SI or mark it as expired. If this is not specified, the SI never expires and should not be automatically deleted. The date must be in the format yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss, for example: push_siexpires=2011-02-27T14:00:00 Required: no Default: no expiry date is set |
push_initiator |
The brand name or number you want associated with the WAP Push. This will replace the originator on some mobile phones. We recommend setting this parameter as well as the smsfrom parameter (when sending bulk SMS messages). Required: no Default: no default |
MMS notifications
How an MMS notification is displayed to an end user is dependent on the mobile phone. For example, some mobile phones may clip or not show the address of the sender (specified by the mms_from parameter). Depending on the mobile phone's settings, once a mobile phone has received an MMS notification it may automatically download the MMS content or just notify the end user.
MMS Notifications are sent as binary data to the operator. Each binary SMS message has a character limit of up to 140 characters before the message must be split. The character length of the following parameters are included in the character limits:
- mms_messagelocation
- mms_transaction_id
- mms_from
- mms_subject
To ensure that the MMS Notification does not require multiple SMS messages, make these parameters as short as reasonably possible.
Parameter |
Description |
---|---|
mms_expire |
The length of time, in minutes, that the message will be available. Setting an expiry time ensures that you do not need to host content indefinitely. However, individual mobile phones may ignore this value and may use another expiry value. There is no defined maximum value for this parameter. The minimum value is 1 (one minute). Required: yes |
mms_messageclass |
The "message class", as per the MMS specification. This enables some mobile phones to filter messages based on their class (for example, to ignore any MMS notification where class=81). There is currently no specific regulatory requirements for setting the MMS message type.
Required: yes |
mms_messagelocation |
The URI of the location hosting the MMS content. This must start with http://. For maximum compatibility with different mobile phones, do not use HTTPS. Required: yes |
mms_messagesize |
The full size of message in bytes. This is passed to the mobile phone so that it can display the file size to the end user before they download the file. The mobile phone should not reject the message if this size is not exactly the same as the file itself. Required: yes |
mms_notification |
This identifies to OpenMarket that the request is for an MMS Notification. You must set this to 1. Required: yes |
mms_transaction_id |
A unique ID generated by your platform to identify the notification request when the mobile phone retrieves the MMS content. This ensures that the platform can deliver dynamic content for each MMS notification sent. This can be an alphanumeric string. Required: yes |
mms_version |
Specifies the MMS specification version number. Currently there is only one version supported, version 1.0. You must set this parameter to 1.0. Required: yes |
mms_from |
Sets an originator for the MMS notification that is displayed to the end user before the MMS message is downloaded. You can set this to any value; however, long values may be clipped by the mobile phone. Some mobile phones may not show this value at all. The value can be a number or email address, in one of these formats: +447700900999/TYPE=PLMN 58870/TYPE=PLMN Some mobile phones may overwrite this with the value of the smsfrom field delivered with the MMS content. Required: no |
mms_subject |
The subject line displayed to the end user for the MMS notification. This can be an alphanumeric string. Required: no |
vCards
The following example request (to a UK number):
user=MyAccount&pass=MyP4S5w0rD&submitid=12345&smsto=447700900750%0A447700900765%0A4477009009990&smsfrom=58870&vcard_data=BEGIN%3AVCARD%0D%0AVERSION%3A2.1%0D%0AFN%3AJohn+Smith%0D%0ATEL%3BWORK%3BVOICE%3A442071231234%0D%0ATEL%3BMOBILE%3BVOICE%3A447700900999%0D%0ATEL%3BHOME%3BFAX%3A442071231235%0D%0AEND%3AVCARD
sends a vCard for John Smith to the number 447700900750. Each line in the vCard must have a carriage return and line feed character (different mobile phones require either one of these characters). The URL encoding for these is %0D%0A.
The example vCard, before being URL encoded, has the following format and content:
BEGIN:VCARD
VERSION:2.1
FN:John Smith
TEL;WORK;VOICE:442071231234
TEL;MOBILE;VOICE:447700900999
TEL;HOME;FAX:442071231235
END:VCARD
Parameter |
Description |
---|---|
vcard_data |
The vCard you are sending. Required: yes |
Header fields
There is no data required in the header.
Response from OpenMarket
OpenMarket acknowledges all requests (accepted or rejected) it receives with an HTTP response.
Accepted requests
When a request is accepted, OpenMarket returns an HTTP response with a 200 status code. The response body will contain a list, separated by line breaks, in the following format:
MSISDN,SMS ID,submitstatus
For example:
447700900750,4276184166,0
The SMS ID is a positive 64 bit integer that uniquely identifies an SMS message as it passes through our systems. Each SMS message accepted in the request is given a unique SMS ID. As well as in these HTTP responses, we will also send SMS IDs with delivery reports and when passing on Mobile Originated SMS messages
The submitstatus identifies the status of the request. If there is no issue with sending the SMS message to the mobile number then the submit status will be 0. If OpenMarket has determined there would be a problem sending an SMS to the mobile number, then an SMS ID is not returned. Instead, a 5 digit submit status code is listed for the number.
This example response shows that OpenMarket will send the SMS message to the UK mobile numbers 447700900750, 447700900765 and 447700900999, and has assigned SMS IDs to these numbers (3900457830 to 3900457832). The submit status code for each number is set to 0:
HTTP/1.1 200 OK
Date: Wed, 05 Aug 2009 11:05:08 GMT
Server: Apache/1.3.26 (Unix) mod_ssl/2.8.8 OpenSSL/0.9.6a
Content-Type: text/plain
Transfer-Encoding: chunked
447700900750,3900457830,0
447700900765,3900457831,0
447700900999,3900457832,0
If the request is for a multipart SMS message, then each part of the message is given an SMS ID, so the response from OpenMarket will include multiple SMS IDs for the same mobile number on separate lines. For example:
.
.
.
447700900750,3900457830,0
447700900750,3900457831,0
447700900765,3900457832,0
447700900765,3900457833,0
447700900999,3900457834,0
447700900999,3900457835,0
You can track the delivery of each SMS message through its SMS ID in the delivery reports from OpenMarket.
Problems with sending the SMS to an individual MSISDN
In the next example, OpenMarket has determined that it cannot send the SMS message to the number 447700900999 and so returns the error code 10702:
HTTP/1.1 200 OK
Date: Wed, 05 Aug 2009 11:05:08 GMT
Server: Apache/1.3.26 (Unix) mod_ssl/2.8.8 OpenSSL/0.9.6a
Content-Type: text/plain
Transfer-Encoding: chunked
447700900750,3900457830,0
447700900765,3900457831,0
447700900999,,10702
This is still an accepted request. OpenMarket will send the SMS message to any mobile number that came back with an SMS ID.
The possible per-message submit status codes are:
- 10200 - This account cannot send to this country
- 10201 - Invalid msisdn
- 10209 - WAP pushes are not supported on this network
- 10701 - Destination is blacklisted
- 10702 - Destination is blocked
- 10703 - Credit limit exceeded
- 10705 - Maximum messages to this MSISDN exceeded
- 10706 - Reverse billing forbidden
To find out more about this codes, See Response error messages below.
The delivery reports for each individual SMS message will show any problem that occurs with their delivery. You can use the SMS ID in the delivery report to track each message.
Rejected requests
If there is a problem with acting on a request, OpenMarket will return a rejected request status code (400, 403 or 500).
The response body will include a submit status code (submitstatus:) and a text description (detail:) of the problem. For example:
submitstatus: 10034
detail: Required parameter submitid missing
Note that, in some cases, the API will ignore an optional parameter in a request (for example, smsfrom in the US) if it would stop the message from being sent.
See Response error messages below for a list of the possible error messages.
Troubleshooting
Unexpected characters in the response
If you receive unexpected characters in an HTTP response from this operation, it may be because we are using chunked transfer encoding, which is part of the HTTP 1.1 specification. These are normally stripped out by the browser or other transfer agent you are using to interface with this API. However, you may see these characters while connecting to this API via Telnet. You can ignore these characters if you see them.
Response error messages
These Submit Status codes are returned in the response body when there was a problem with receiving a request.
10001-10706 status codes
Submit status |
Detail |
Description |
---|---|---|
10001 - 10025 | Required parameter <name> missing | The request has an invalid or missing parameter (<name>). Either the parameter is missing from the request or it is misspelled in the request. |
10100 - 10116 | Bad <name> parameter | The value for a required parameter <name> is invalid. For example, you would get this response if you specified a letter rather than a number for the report parameter. Check that the value uses the correct format before resubmitting the request. These errors are returned for required parameters but not optional parameters. |
10200 |
This account cannot send to this country |
Your account cannot send a message to the number as it is registered in a country you cannot send messages to. Talk to your OpenMarket account manager about sending messages to this region. Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response. |
10201 |
Invalid msisdn |
The mobile number appears to be an incorrect length or includes non-numerical characters. Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response. |
10203 | Message too long | The message is too large to send in its current format. This will be either because it exceeds the number of parts the message type can have (between 2 and 5 parts), or you have not requested it to be sent as a multipart message. Either resubmit a shorter message or send the message as a multipart message. |
10204 | Failed to decode message | OpenMarket could not decode the message content as it was not correctly hex-encoded. The message type you are sending requires the message contents to be hex-encoded. |
10207 | Request type unknown | The format of the request did not include all the parameters you require to send any message type. For example, you would receive this error message if your request contained only the user, pass and smsto parameters. |
10209 |
WAP pushes are not supported on this network |
The end user is with a mobile operator that does not support WAP Pushes. You will need to send the URL to the end user as a plain-text SMS with the URL included. Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response. |
10210 | Submitid too long | The value of the submitid parameter exceeds the maximum allowed length (30 characters). |
10500 | Bad image data | The image sent in the request was not correctly hex-encoded. |
10501 | Could not decode image data | The image was correctly hex-encoded, but is not in an image format supported by this API. This API supports BMP, GIF, JPEG and PNG. |
10551 | Invalid URL | Your request included a parameter that requires a URL. The value of this parameter must begin with either either http:// or https://. OpenMarket will also check that URLs with a 'www' subdomain include 3 'w' characters. Format the URL correctly before resending the request. |
10552 | Invalid expiration date |
The value of the push_siexpires parameter must be a date in the format yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss, where 'T' is literally the character T. For example: push_siexpires=2011-02-27T14:00:00 |
10553 | Action requires si-id | You have specified push_action=4 in a WAP Push message request. This action deletes a WAP Push on an end user's cell phone. You must also specify the push_siid parameter to identify the WAP Push you wish to delete. |
10554 | Invalid push type | For WAP Push message requests only. The value you specified for the pushtype parameter is incorrect. For WAP Push Service Indication requests, you must specify 0 for this parameter. |
10560 | Only http method POST is accepted |
This status occurs only for broadcast requests. Requests to the broadcast endpoints must be sent via HTTP POST. |
10561 | Too many concurrent requests |
This status occurs only for broadcast request. This endpoint cannot accept the broadcast request, as it is currently processing the maximum number of broadcast SMS requests it will accept at the same time. Wait one minute then resubmit the rejected request. |
10562 | Request still processing |
This status occurs only for broadcast requests. The request has the same submitid of a request you have very recently sent (within the last minute). After OpenMarket has finished processing the original request, we will return an HTTP 200 response. If you are attempting to send a different request, then change the value of the submitid parameter before resubmitting the request. |
10700 | Bad username/password | Either the value of the user or pass parameter is not correct. |
10701 |
Destination is blacklisted |
The mobile number is currently in the number blacklist. Contact your OpenMarket account manager for more information. Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response. |
10702 | Destination is blocked |
The mobile number cannot receive the type of SMS message you are sending, or the number is outside the range of mobile operators that we can send that type of message to. Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response. |
10703 | Credit limit exceeded |
The request was rejected as sending the SMS messages would exceed your monthly per-account credit limit. Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response. |
10704 | You are not authorized to send messages from that IP address | The request did not come from one of the IP addresses in the whitelist you provided to OpenMarket. You can only submit requests from the IP addresses in your whitelist. Contact OpenMarket Support if you need to change the addresses in this whitelist. |
10705 | Maximum messages to this MSISDN exceeded |
You have reached the maximum number of messages you can send to this mobile number in a day. Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response. |
10706 | Reverse billing forbidden |
The end user has not opted in to your premium rate service on this short code. Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response. |
10900-10902 status codes
Submit status |
Detail |
Description |
---|---|---|
10900 - 10902 |
Internal error Provisioning error |
There was a problem that stopped OpenMarket from receiving your request. Retry the request after a minute. |