HTTP MMS

Receive an MMS

OpenMarket sends MMS messages as HTTP POST requests. There are no parameters included in the request URL.

Quick facts

Method	POST with JSON and MIME parts.
Response required	HTTP 200 with empty body.
Available	US, UK, Ireland, Australia.
Prerequisites	You must have MMS messaging provisioned with OpenMarket.
Encoding	Base64
More information	See Overview.

Request from OpenMarket

Header fields

Copy

Example Header

POST /customerEndpoint HTTP/1.1
Host: example.com
X-Request-Id: 015-3DD6C366-D68A-4A02-9777-19CBC8AB40C1
Content-Type: multipart/mixed; boundary=mimeboundary

Custom fields

Field	Description
customerEndpoint	This is your endpoint or callback URL.
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

Field

Description

customerEndpoint

This is your endpoint or callback URL.

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

Request body

The request body contains the details of the MO message and the contents of the MMS message.

The body is specified as MIME multipart. The first MIME part should be the sending details, in JSON. The MMS message contents should follow next in MIME multiparts.

Copy

Example MO MMS Message

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
POST /customerEndpoint HTTP/1.1
Host: example.com
X-Request-Id: 015-3DD6C366-D68A-4A02-9777-19CBC8AB40C1
Content-Type: multipart/mixed; boundary=mimeboundary 
--mimeboundary
Content-Type: application/json
Content-Id: main 
{
   "type": "MO",
   "moId": 123456789012345,
   "source": "447800000001",
   "destinations": ["88600"],
   "ccs": ["88602"],
   "bccs": [],
   "date": "2014-07-16T19:20:30+00:00",
   "mobileOperatorId": 77,
   "subject": "Test MMS",
   "userAgent": "HTC One"}
--mimeboundary
Content-Type: image/jpeg
Content-Id: image.jpg 
...
--mimeboundary
Content-Type: text/plain
Content-Id: text.txt 
This is a text attachment
--mimeboundary--

JSON properties

Field	Description
type	Indicates the type of MMS event occurring. Requests sent by OpenMarket may be either "MO" for MO MMS messages or "REPORT" for delivery reports. Type: string Returned: Always
moId	A unique OpenMarket ID for the MMS you have received. Type: number Returned: Always
source	The mobile number from which the MMS message was sent. Type: string Returned: Always
destinations	The address (e.g. short code, long code, toll-free text-enabled number, etc) of the message recipient. OpenMarket sends only one recipient (To), which is the short code. Type: string Returned: Always
ccs	Any numbers to which the user sent the message using the "CC" field in the MMS message. Type: string Returned: Always
bccs	Any numbers to which the user sent the message using the "BCC" field in the MMS message. Because this is a BCC field, only your own number would be visible. Type: string Returned: Always
date	The time and date that OpenMarket received the MMS message from the mobile operator. This is a timestamp in the format: YYYY-MM-DDThh:mm:ssTZD The time zone indicated is relative to UTC. Type: string Returned: Always
mobileOperatorId	A numeric ID representing the mobile operator we received the message from. This is an OpenMarket ID; e.g., 383 for AT&T in the US. For a list of mobile operator IDs see Mobile Operator IDs. Type: number Returned: Always
subject	The subject line of the MMS message. This has a maximum length of 255 characters. Type: string Returned: Always
userAgent	The user agent of the mobile phone. Type: string Returned: Only when provided by the mobile operator.

Responding to the request

Your platform should respond with an HTTP 200 response with an empty body. This response must be given in a timely manner (within 10 seconds).

OpenMarket will retry the request if it does not receive a response from your platform within 60 seconds, or receives a non-200 response. You will need to make sure that you filter duplicate requests.

Testing your integration

See Testing Your MMS Integration.

Troubleshooting

I'm not receiving any MMS messages

If you do not receive requests from us to an HTTPS URL, but you can receive them over standard HTTP, a possible cause is that we do not recognize and trust your server's security certificate. You must obtain an additional certificate from one of the trusted certification authorities.