MEP APIs

Submit an SMS Broadcast

This operation enables you to broadcast an SMS to a subscription or multiple subscriptions.

The message parameter may contain expression language (EL). If there is EL in the message, the API cannot determine the:

Message length, so will not reject any request on this basis
Character set used in the message, so will not reject a request if there are non-GSM characters (and you have requested not to send messages with non-GSM characters).

However, when processing the broadcast, each message is still passed through message length and character support checks after the EL is resolved. This means messages that fail these checks are still filtered from the broadcast.

Quick facts

Method	GET
Returns	Accepted response: XML Rejected response: plain text
Available	All regions
Prerequisites	You must have MEP provisioned with OpenMarket, and the following roles set in the user account: Main Roles: Broadcast User Broadcasts - Broadcast Types System - Accounts The MEP account will require access to the SMS-specific Gateway Account.
More information	See MEP Operations and Making Broadcast Requests.

Try It Out

If you'd like to try out this call using cURL, see Making Broadcast Requests, which will take you through sending SMS, MMS and Service broadcasts, and retrieving any IDs you need to know.

Making a Request

Definition

GET https://cmx2api.openmarket.com/broadcastapi/v1/createsmsbroadcast

URL example

https://cmx2api.openmarket.com/broadcastapi/v1/createsmsbroadcast?username=MyUsername&password=P4S5W0Rd&subscriptions=A1B2C3D4E5F6%2CB2C3D4E5F6A1&account=F9E8D7C6B5A4&name=Team+Spirit&message=Thanks+for+joining+us+last+week%21&charactersupport=gsm&multipart=false

Query parameters

Parameters must be URL encoded.

Parameter	Description
username	The username used to access MEP. Required: yes Type: string
password	The password associated with the MEP username. Required: yes Type: string
subscriptions	The IDs of the subscriptions that you want to broadcast the message to. Use a comma separated list to specify multiple subscription IDs. Required: yes Type: string
account	The account API ID of the SMS Gateway Account through which you want to send the messages. This is provided by OpenMarket, and is a unique ID used only for sending SMS through MEP. For information about retrieving the ID, see Making Broadcast Requests. Required: yes Type: string
name	The name used to identify the broadcast activity in MEP. This can be up to 255 characters in length. Required: yes Type: string
message	The SMS message you are broadcasting. You can send messages using either the GSM or UCS-2 character sets. Using the UCS-2 character set halves the message length: If you use GSM, the message can be up to 160 characters long, or 1530 characters if you are sending a multipart message (up to 10 parts). If you use UCS-2, the message can be up to 70 characters long, or 670 characters if you are sending a multipart message (up to 10 parts). The message will not be sent if it contains characters outside of the GSM and UCS-2 character sets. The charactersupport parameter determines how the message is encoded. Required: yes Type: string
charactersupport	Determines what action is taken if the message contains non-GSM characters. By default, MEP will send messages that use only GSM characters as a GSM encoded message, regardless of the value set for this parameter. Options: ucs2 — The message is sent using the UCS-2 character set. This may require more message parts to send. gsm — The message is sent using the GSM character set. The non-GSM characters are converted to the nearest GSM equivalent. However, characters with no near equivalent may be converted to unexpected characters, or question marks. donotsend — The message is not sent. Required: yes Type: string
multipart	Enables multipart messaging for this message. The message is sent as multipart only if it too large for a single SMS message. The maximum number of parts that MEP will split a message into is ten (1530 characters for GSM and 670 characters for UCS-2). You are charged per SMS message part for multipart messages. IMPORTANT Although OpenMarket supports SMS messages that are up to ten parts, there are many mobile operators and regions that do not support this maximum limit. Most mobile operators do, however, support up to four-part SMS. If you are considering sending multipart messages longer than four parts, please ensure that you test the message across the range of mobile operators relevant to the service, and speak to your OpenMarket account manager for more advice. Options: true — The message is sent as multipart, if required. If the message is more than 10 parts, it is not sent. false — The request is rejected if the message text exceeds a single SMS message. Required: yes Type: Boolean
senddate	The time and date that the message is broadcast to end users (based on UK time). This enables you to create a message that MEP sends at the specified time, rather than immediately. Specify this in the format yyyy-MM-dd HH:mm:ss, for example: 1999-12-31 23:59:59 MEP assumes this is the time and date for London, United Kingdom (either GMT or BST, depending on the time of year). If you are based in another region, you will need to offset the time, e.g. by 8 hours for Pacific Standard time. Note that if you specify a time in the past, then MEP broadcasts the message immediately. Required: no Type: string Default: the current date and time
originator	The originator details sent with the message. This identifies to the end user who sent the message. This can be a short code, a virtual mobile number (up to 16 digits), or a text string (up to 11 characters). On accounts where you cannot change the originator this value is ignored. Required: no Type: string Default: no default
flash	Whether the message is sent as a flash SMS message or a normal SMS message. Flash messages are instantly displayed on an end users phone and are not automatically saved to the phone message inbox. Options: true — The message is sent as a flash message. false — The message is not sent as a standard message. Required: no Type: Boolean Default: false
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 160 characters in length. If you are using Reporting Insights, then this value appears in the SMS Detailed data source as note 2. Required: no Type: string Default: no default
subaccount	Use this field to classify your messaging into different groups in MEP reports. The value does not need to already exist in MEP. It can be up to 10 characters in length. If you are using Reporting Insights, then this value appears in the SMS Detailed and SMS Summary data sources as subaccount. Required: no Type: string Default: no default

Parameter

Description

username

The username used to access MEP.

Required: yes

Type: string

password

The password associated with the MEP username.

Required: yes

Type: string

subscriptions

The IDs of the subscriptions that you want to broadcast the message to. Use a comma separated list to specify multiple subscription IDs.

Required: yes

Type: string

account

The account API ID of the SMS Gateway Account through which you want to send the messages. This is provided by OpenMarket, and is a unique ID used only for sending SMS through MEP.

For information about retrieving the ID, see Making Broadcast Requests.

Required: yes

Type: string

name

The name used to identify the broadcast activity in MEP. This can be up to 255 characters in length.

Required: yes

Type: string

message

The SMS message you are broadcasting.

You can send messages using either the GSM or UCS-2 character sets. Using the UCS-2 character set halves the message length:

If you use GSM, the message can be up to 160 characters long, or 1530 characters if you are sending a multipart message (up to 10 parts).
If you use UCS-2, the message can be up to 70 characters long, or 670 characters if you are sending a multipart message (up to 10 parts).

The message will not be sent if it contains characters outside of the GSM and UCS-2 character sets.

The charactersupport parameter determines how the message is encoded.

Required: yes

Type: string

charactersupport

Determines what action is taken if the message contains non-GSM characters.

By default, MEP will send messages that use only GSM characters as a GSM encoded message, regardless of the value set for this parameter.

Options:

ucs2 — The message is sent using the UCS-2 character set. This may require more message parts to send.
gsm — The message is sent using the GSM character set. The non-GSM characters are converted to the nearest GSM equivalent. However, characters with no near equivalent may be converted to unexpected characters, or question marks.
donotsend — The message is not sent.

Required: yes

Type: string

multipart

Enables multipart messaging for this message. The message is sent as multipart only if it too large for a single SMS message.

The maximum number of parts that MEP will split a message into is ten (1530 characters for GSM and 670 characters for UCS-2).

You are charged per SMS message part for multipart messages.

IMPORTANT Although OpenMarket supports SMS messages that are up to ten parts, there are many mobile operators and regions that do not support this maximum limit. Most mobile operators do, however, support up to four-part SMS. If you are considering sending multipart messages longer than four parts, please ensure that you test the message across the range of mobile operators relevant to the service, and speak to your OpenMarket account manager for more advice.

Options:

true — The message is sent as multipart, if required. If the message is more than 10 parts, it is not sent.
false — The request is rejected if the message text exceeds a single SMS message.

Required: yes

Type: Boolean

senddate

The time and date that the message is broadcast to end users (based on UK time). This enables you to create a message that MEP sends at the specified time, rather than immediately.

Specify this in the format yyyy-MM-dd HH:mm:ss, for example:

 1999-12-31 23:59:59

MEP assumes this is the time and date for London, United Kingdom (either GMT or BST, depending on the time of year). If you are based in another region, you will need to offset the time, e.g. by 8 hours for Pacific Standard time.

Note that if you specify a time in the past, then MEP broadcasts the message immediately.

Required: no

Type: string

Default: the current date and time

originator

The originator details sent with the message. This identifies to the end user who sent the message. This can be a short code, a virtual mobile number (up to 16 digits), or a text string (up to 11 characters). On accounts where you cannot change the originator this value is ignored.

Required: no

Type: string

Default: no default

flash

Whether the message is sent as a flash SMS message or a normal SMS message. Flash messages are instantly displayed on an end users phone and are not automatically saved to the phone message inbox.

Options:

true — The message is sent as a flash message.
false — The message is not sent as a standard message.

Required: no

Type: Boolean

Default: false

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 160 characters in length.

If you are using Reporting Insights, then this value appears in the SMS Detailed data source as note 2.

Required: no

Type: string

Default: no default

subaccount

Use this field to classify your messaging into different groups in MEP reports. The value does not need to already exist in MEP. It can be up to 10 characters in length.

If you are using Reporting Insights, then this value appears in the SMS Detailed and SMS Summary data sources as subaccount.

Required: no

Type: string

Default: no default

Header fields

There is no data required in the header.

Response from OpenMarket

Accepted requests

MEP will respond to a successful request with a status code of 200 and an ID for the broadcast in the response body.

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 16:36:54 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Content-Type: text/plain
			
<?xml version="1.0" encoding="ISO-8859-1"?>
<broadcast>
   <id>17567FCA39AF3F67</id>
</broadcast>

Rejected requests

If your request is rejected then the body of the response will contain a plain text description of the error. For example:

HTTP/1.1 400 Bad Request
Date: Tue, 15 Mar 2016 11:48:56 GMT
Server: Apache-Coyote/1.1
Connection: close
Transfer-Encoding: chunked
Content-Type: text/plain
			
Your request is invalid, specifically the following parameter is incorrect: charactersupport=whoops

See Response error messages below for a list of the possible error messages.

Testing your integration

You can test broadcast operations directly with MEP, however, MEP will send any messages to numbers in the specified subscriptions. Therefore to test your integration, we suggest the following:

Create a subscription with no numbers in the list. This is suitable for testing your requests and ability to receive responses from us.
Once you are ready, create a subscription that contains your own test mobile number(s), to confirm that your broadcasts work as you expect. If you are messaging in multiple regions, then we recommend using multiple test numbers that are located in your messaging regions.

For more information on using each operation, see Making Broadcast Requests.

Troubleshooting

Response error messages

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

Message	Description
Your request is invalid, specifically the following parameter is incorrect: <parameter>=<value>	You request contains a problem with the specified mandatory parameter that has stopped MEP from being able to process the request. If the <value> is “null”, then the parameter name is misspelled or the parameter is missing. Otherwise, the value you specified is invalid or does not match the available options. Correct the error and resend the message.
Message contains non-GSM characters and cannot be sent.	OpenMarket rejected the message because you have requested that MEP does not send messages that contain non-GSM characters. This option is set using the charactersupport parameter. Note that if the message parameter contains any expression language, then MEP cannot determine the character set used in the message at the point of accepting the request, so will not reject a request if there are non-GSM characters.
Message too long for singlepart SMS. Encoded message length was: <number>. Max length: 160 GSM characters	The message text in the request exceeds 160 characters. By default, MEP restricts broadcast SMS messages to single-part messages (up to 160 characters). If you want to send the message as a multipart message, include multipart=true in the request. Note that you will be charged for each part of a multipart message. Note that if there is an expression in the message, the API cannot determine the message length, so will not reject any request on this basis.
Message too long for multipart SMS. Encoded message length was: <number>. Max length: 1530 GSM characters	MEP restricts broadcast multipart messages to up to ten message parts (1530 characters). You will need to reduce the message text to under 1530 characters to successfully send the broadcast. Note that you are charged for each SMS message part that makes up a multipart message. IMPORTANT Although OpenMarket supports SMS messages that are up to ten parts, there are many mobile operators and regions that do not support this maximum limit. Most mobile operators do, however, support up to four-part SMS. If you are considering sending multipart messages longer than four parts, please ensure that you test the message across the range of mobile operators relevant to the service, and speak to your OpenMarket account manager for more advice. Note that if there is an expression in the message, the API cannot determine the message length, so will not reject any request on this basis.
Your username and/or password is incorrect. Check and try again.	Either the username or the password parameter has not been correctly specified. Both parameters are mandatory. Check that both parameters are specified, and that you have entered the correct values for each parameter.
You do not have the necessary roles or permissions to perform the action: <description>	Your access rights in MEP do not allow you use the operation. The information in the <description> part of the response will tell you the role or permission that you are missing.