MEP APIs

Submit an MMS Broadcast

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

MEP immediately retrieves the ZIP file containing the MMS message. This means that the file must exist at the specified URL before you send this request. For details on how to construct the ZIP file, see Creating an MMS zip file for a broadcast MMS message.

You can only broadcast MMS messages if you have an MMS-capable MEP account. Contact your OpenMarket account manager to provision this.

Quick facts

Method	GET
Returns	Accepted response: XML Rejected response: plain text
Available	United States, United Kingdom, Ireland and Australia.
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 MMS-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/subscriptionapi/createmmsbroadcast

URL example

https://cmx2api.openmarket.com/subscriptionapi/createmmsbroadcast?username=MyUsername&password=P4S5W0Rd&subscriptions=A1B2C3D4E5F6%2CB2C3D4E5F6A1&account=F9E8D7C6B5A4&contents=http://example.com/happyday.zip&name=Happy+campaign&subject=Have+a+happy+day+on+us&senddate=2016-04-05+13%3A00%3A00&pickdate=2016-03-31+23%3A59%3A00&originator=ACME+inc&note=new+campaign+launch&subaccount=Happy+day

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 MMS Gateway Account through which you want to send the messages. This is provided by OpenMarket, and is a unique ID used only for sending MMS 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
contents	The location of the MMS content ZIP file. This must be a URL that MEP can access. Required: yes Type: string
subject	The subject for the MMS. This is visible to the end user and can be up to 255 characters in length. Required: yes Type: string
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. If you do not specify a pickdate value, then MEP uses the senddate value you sent (not the current time) as the default pick date. 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
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 MMS Gateway Account through which you want to send the messages. This is provided by OpenMarket, and is a unique ID used only for sending MMS 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

contents

The location of the MMS content ZIP file. This must be a URL that MEP can access.

Required: yes

Type: string

subject

The subject for the MMS. This is visible to the end user and can be up to 255 characters in length.

Required: yes

Type: string

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. If you do not specify a pickdate value, then MEP uses the senddate value you sent (not the current time) as the default pick date.

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

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" ?>
<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 401 Unauthorized
Date: Tue, 15 Mar 2016 11:48:56 GMT
Server: Apache-Coyote/1.1
Connection: close
Transfer-Encoding: chunked
Content-Type: text/plain

Your username and/or password is incorrect. Check and try again.

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