Send an MMS

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

Quick facts

Method

POST with JSON and MIME parts.

Returns

JSON

Available

US, UK, Ireland, Australia.

Prerequisites

You must have MMS messaging provisioned with OpenMarket.

More information

See Overview.

Making a Request

Copy

Definition

POST https://mms.openmarket.com/mms/v2/send

There are no URL parameters for this endpoint.

This endpoint supports version Transport Layer Security (TLS) 1.2.

If you have services that will require high throughput or high availability, you can connect directly to the data centers; see Direct data center connections.

Mime headers

For most mime parts, you will need to provide the following headers: Content-Type, Content-Id, and Content-Transfer-Encoding.

Content ID recommendations

The content ID is a unique identifier for the content part. When specifying each content ID in your requests, we recommend that you:

  • Don't include any angle brackets around a content ID
  • Don't include spaces or anything other than basic letters/numbers
  • Keep the IDs shorter than 20 characters

Content Transfer Encoding

The default encoding for any content is always binary. Therefore, if you are using another encoding, you must specify this in the mime header.

Header fields

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

Copy

Example Header

POST /mms/v2/send HTTP/1.1
Host: mms.openmarket.com
Content-Type: multipart/mixed; boundary=mimeboundary
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 multipart/mixed; boundary=mimeboundary for MMS requests.

Request body

The request body must contain the details for sending the message, and the MMS message contents or links to this content. The body is specified as MIME content types. The first mime part should be the sending details, in JSON. The MMS message contents should follow next.

Note: Include a blank line above each --mimeboundary, or the request will fail with a 400 error.

Attachments may be base-64 encoded.

OpenMarket will only accept requests with at least one piece of content specified. This can be either as an embedded attachment or as a link.

Content Caching

The Content-Type to use for supplying the URL is:

Copy 
Content-Type: application/vnd.openmarket.remoteContent

For example:

Copy 
--mimeboundary
Content-Type: application/vnd.openmarket.remoteContent
Content-Id: MMS-Demo.mp4 
https://www.openmarket.com/docs/Content/downloads/MMS-Demo.mp4
--mimeboundary

Headers to include with the externally hosted content

The HTTP header for the content must include the Content-Type field, so that we know what the content is. For example, a .png image should use: Content-Type: image/png.

When OpenMarket retrieves the content item, we will heed the "Cache-Control" and "Expires" HTTP headers provided with the content item.

Best practices

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.

Example request

In this example, the three content items are all working examples.

Copy 
POST /mms/v2/send HTTP/1.1
Host: mms.openmarket.com
Content-Type: multipart/mixed; boundary=mimeboundary
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
--mimeboundary
Content-Type: application/json
Content-Id: main

{
   "type": "MT",
   "source": "88600",
   "destination": "12515550130",
   "mtConfig": "config1",
   "subject": "Example MMS",
   "mobileOperatorId": 77  
}

--mimeboundary
Content-Type: application/vnd.openmarket.remoteContent
Content-Id: MMS-Demo.mp4 
https://www.openmarket.com/docs/Content/downloads/MMS-Demo.mp4
--mimeboundary
Content-Type: text/plain; charset=utf-8
Content-Id: example.txt 
This is my text.

--mimeboundary
Content-Type: image/png
Content-Id: example.png
Content-Transfer-Encoding: BASE64 
iVBORw0KGgoAAAANSUhEUgAAAA4AAAAMCAMAAABlXnzoAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyJpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2LjE0NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wTU09Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9tbS8iIHhtbG5zOnN0UmVmPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvc1R5cGUvUmVzb3VyY2VSZWYjIiB4bWxuczp4bXA9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC8iIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6QkQ0NkRDOUI4Nzc5MTFFNEFFNDRBNDcwQ0FFMUEyMjciIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6QkQ0NkRDOUE4Nzc5MTFFNEFFNDRBNDcwQ0FFMUEyMjciIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNiAoV2luZG93cykiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmRpZDpCNDFBNTkyQzc5ODdFNDExQjRCQkEwQTRBNTNGRUU1MCIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDpCNDFBNTkyQzc5ODdFNDExQjRCQkEwQTRBNTNGRUU1MCIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/PuLg5qAAAABLUExURWyNujFfnqu9kOPp2qG2hIWgX8fTtaa61V2Bs052rJiveGqLO9Lc6o+obImkyNDawdnizvX38rTFnbXG3HyZU3OSRxRJkezw5v///zxUK60AAABxSURBVHjaTIxJEsMwCASxvCXRLoGY/780qOxyuU8MTEMAtO3e85ZtJKC5XIHVMavFtuLGSSGteMizHFIw/9oSaCzDlAiUCDpHQB/9JxVRQOlrnSXt0jL75+pV+LAyPtNVwcaQ+bmnDj2gBWXGN38BBgBPtAxu5tsshAAAAABJRU5ErkJggg==

--mimeboundary--














JSON properties

Field

Description

type

Indicates the type of MMS event occurring. If you are sending an MT MMS message, the only valid value is "MT".

Type: string

Required: Always

source

 

The originator (or sender) of the message; i.e. your contact number as seen by the end user. In the US, this must be an MMS-specific short code or toll-free, text-enabled number. In the UK, this can be either a short code or a virtual mobile number. If supplying a virtual mobile number, the number must be in international format (e.g. 447700900750) and without a leading "+" character.

Type: string

Required: Always

destination

The mobile number to which you are sending the MMS message. The number must be in international format (e.g. 447700900765) and without a leading "+" character.

Type: string

Required: Always

mtConfig

The MT configuration you wish to use for this message. For more information about MT configurations, see MT and MO configurations.

Type: string

Required: Always

subject

The subject line for the MMS message. This displays on the end user's handset, often either above the content or along with the source (originator) of the MMS.

Note that you cannot specify only whitespace as the value (e.g. " ").

Type: string

Required: No

Length: 1-255 characters (if working with multiple carriers, the recommended length is 80.)

mobileOperatorId

A numeric ID representing the mobile operator as known by OpenMarket; e.g., 383 for AT&T in the US. If you do not specify a mobile operator, then OpenMarket will perform an operator lookup on your behalf.

For a list of mobile operators that support MMS, see Supported Mobile Operators and Limitations.

Type: number

Required: No

Response from OpenMarket

Accepted requests

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

Copy 
HTTP/1.1 202 Accepted
X-Request-Id: 015-3DD6C366-D68A-4A02-9777-19CBC8AB40C1
Content-Type: application/json 
{
   "mtId": 123456789012345
}

The response will include the following data.

Field

Description

X-Request-Id

A unique ID that identifies the specific request 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.

Type: A string of 1 to 30 characters in length.

Returned: Always

mtId

A unique OpenMarket ID for the MMS you have sent. Delivery reports use this ID to identify the MMS message they are reporting on.

Type: integer

Returned: Always

Rejected requests

If your request is rejected then the body of the response will contain a code that identifies the error. For example:

Copy 
HTTP/1.1 403 Forbidden
X-Request-Id: 015-3DD6C366-D68A-4A02-9777-19CBC8AB40C1
Content-Type: application/json 
{
   "error": { 
      "code": 15102,
      "description": "You must specify a source number"
   }
}

The response will include following data.

Field

Description

X-Request-Id
  • Make each piece of content available at its URL for at least three days after your last request. This ensures that OpenMarket can still access the content in the unlikely situation of a mobile operator or network disruption causing message retries and delays. OpenMarket only caches the content for a limited time, and your message processing may be split over multiple data centers, which will each fetch the content item separately.
  • Use a unique URL for new content (e.g. do not recycle the location). This ensures that we never use a previously cached version of content instead of new content.

Type: A string of 1 to 30 characters in length.

Returned: Always

code

Code defining the reason for the outcome of the request. For a list of the codes, see Response error codes below.

Returned: Always

description

Natural language description of the error.

Returned: Always

Testing your integration

OpenMarket provides an option for testing your integration with the production environment. See Testing Your MMS Integration.

Troubleshooting

Response error codes

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

Field

Description

15000

An internal error has occurred - please contact the OpenMarket Support team for more information.

15100

You must specify a message type.

The type field is missing.

15101

You must specify a destination number.

The destination field is missing.

15102

You must specify a source number.

The source field is missing.

15105

You must specify an mtConfig.

The mtConfig field is missing.

15200

Invalid message type.

The type field has an incorrect value or type. Accepted values are "MT" for the /send call and "MO" for an incoming MMS.

15201

Invalid destination number.

The destination field has an incorrect value or type.

15202

Invalid source number.

The source field has an incorrect value or type.

15203

Invalid subject.

The subject field has an incorrect value or type. The maximum value of the subject cannot exceed 255 characters, but some carriers may have different character limitation. If working with multiple carriers, it's generally recommended not to exceed 80 characters.

15204

Invalid mobileOperatorId.

The mobileOperatorId field has an incorrect value or type.

15205

Invalid mtConfig.

The mtConfig field has an incorrect value or type.

15206

Authentication error, check your username and password.

The request includes invalid credentials. If you do not remember your login credentials, contact OpenMarket Support.

15300

IP not allowed.

The request was made from an IP address that was not white listed when the account was set up. Contact OpenMarket Support.

15301

Maximum requests per day for that user exceeded.

15302

Maximum requests per month for that account exceeded.

15303

Prepay Credit limit exceeded.

15305

Authentication error, this account is closed.
15406

TPS limit exceeded.

The TPS limit has been exceeded and any messages over this limit are rejected. This is a retryable error.