Send an MMS

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

Quick facts


POST with JSON and MIME parts.




US, UK, Ireland, Australia.


You must have MMS messaging provisioned with OpenMarket.

More information

See Overview.

Making a Request




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.


Example Header

POST /mms/v2/send HTTP/1.1
Content-Type: multipart/mixed; boundary=mimeboundary
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=




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.


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.

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:

Content-Type: application/vnd.openmarket.remoteContent

For example:

Content-Type: application/vnd.openmarket.remoteContent
Content-Id: MMS-Demo.mp4

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.

POST /mms/v2/send HTTP/1.1
Content-Type: multipart/mixed; boundary=mimeboundary
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 
Content-Type: application/json
Content-Id: main
   "type": "MT",
   "source": "88600",
   "destination": "12515550130",
   "mtConfig": "config1",
   "subject": "Example MMS",
   "mobileOperatorId": 77  
Content-Type: application/vnd.openmarket.remoteContent
Content-Id: MMS-Demo.mp4
Content-Type: text/plain; charset=utf-8
Content-Id: example.txt 
This is my text.
Content-Type: image/png
Content-Id: example.png
Content-Transfer-Encoding: BASE64 

JSON properties




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



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


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


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


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


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:

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.




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


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:

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.




  • 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 defining the reason for the outcome of the request. For a list of the codes, see Response error codes below.

Returned: Always


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.


Response error codes

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




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


You must specify a message type.

The type field is missing.


You must specify a destination number.

The destination field is missing.


You must specify a source number.

The source field is missing.


You must specify an mtConfig.

The mtConfig field is missing.


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.


Invalid destination number.

The destination field has an incorrect value or type.


Invalid source number.

The source field has an incorrect value or type.


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.


Invalid mobileOperatorId.

The mobileOperatorId field has an incorrect value or type.


Invalid mtConfig.

The mtConfig field has an incorrect value or type.


Authentication error, check your username and password.

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


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.


Maximum requests per day for that user exceeded.


Maximum requests per month for that account exceeded.


Prepay Credit limit exceeded.


Authentication error, this account is closed.


TPS limit exceeded.

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