HTTP MMS

Receive an MMS Delivery Report

Delivery reports inform you of the final delivery state for a message and can contain information about the handset, which is useful for device discovery.

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

Quick facts

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

Request from OpenMarket

The request from OpenMarket includes data in the header field and request body. There are no parameters included in the request URL.

Header fields

Copy

Example Header

POST /customerEndpoint HTTP/1.1
Host: example.com
X-Request-Id: 015-3DD6C366-D68A-4A02-9777-19CBC8AB40C1
Content-Type: application/json

Custom fields

Field	Description
customerEndpoint	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

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 delivery details for an MT MMS message in JSON format.

Copy

Example Delivery Report

1
2
3
4
5
6
7
8
9
10
11
12
13
POST /customerEndpoint HTTP/1.1
Host: example.com
X-Request-Id: 015-3DD6C366-D68A-4A02-9777-19CBC8AB40C1
Content-Type: application/json                
 {
  "type": "REPORT",
  "mtId": "123456789012345",
  "date": "2014-07-16T19:20:30+00:00",
  "status": "Rejected",
  "outcomeId": 9,
  "outcomeDescription": "Recipient not found on mobile operator",
  "userAgent": "HTC One"
 }

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
mtId	A unique OpenMarket ID for an MMS you have sent. This identifies the MMS for which we are sending the delivery report. Type: string Returned: Always
date	The time and date that OpenMarket received the delivery report 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
status	The final status reported for the MMS message delivery. This can be one of: Deferred Expired Forwarded Indeterminate Rejected Retrieved Unrecognized See Delivery report states below. Type: string Returned: Always
outcomeId	An ID that identifies the specific reason why the delivery report has returned the specific status. See Delivery report states below. Type: integer Returned: Always
outcomeDescription	A text description that describes the specific reason why the delivery report has a certain status. Type: string Returned: Always
userAgent	The user agent of the mobile phone. This identifies the type of mobile phone. Type: string Returned: When known

Delivery report states

The following table lists the responses returned with delivery reports. Search for an Outcome ID, Status, or any part of a description:

Status	Outcome ID	Outcome description
Retrieved	1	Success. The message was successfully sent to the handset.
Deferred	4	Deferred. The end user's handset has retrieved the MMS header, but has not downloaded the full message from the mobile operator. The end user may still download the message at a later time.
Forwarded	5	Forwarded. The end user forwarded the MMS to another address without retrieving it.
Expired	6	Expired. The mobile operator could not contact the handset before reaching the expiry time. Each mobile operator has their own expiry times after which they will stop trying to send messages such as an MMS.
Unrecognized	7	Unrecognized. The end user's handset cannot download the MMS.
Indeterminate	8	Indeterminate. The mobile operator could not determine if the message was delivered correctly. This occurs when the handset cannot return an MMS delivery report.
Rejected	2	System error. OpenMarket experienced a technical issue with sending the message. Please contact OpenMarket Support or wait for a notification from OpenMarket about the issue.
Rejected	3	Rejected. This error normally occurs when a mobile operator initially accepted the message but then determines that the mobile number is not registered.
Rejected	9	Recipient not found on mobile operator.
Rejected	10	Source number is not provisioned for use with this mobile operator. Contact your OpenMarket Account Manager to ensure that you are provisioned with the correct mobile operators.
Rejected	11	Recipient blocked by mobile operator.
Rejected	12	DRM not supported. This may be from either the mobile operator or the end user's handset.
Rejected	13	Content blocked or not supported by mobile operator or handset.
Rejected	14	Invalid subject - maximum length exceeded. The subject line of the MMS is too long. You will need to shorten the subject length before retrying the MMS message.
Rejected	15	Short code blocked by end user.
Rejected	16	Unable to determine mobile operator.
Rejected	17	Recipient deactivated.
Rejected	18	Recipient suspended.
Rejected	19	Recipient does note support MMS.
Rejected	20	Campaign blocked by mobile operator. Your campaign is identified in the MT configuration. In the US particularly, mobile operators will block messages if the associated campaign has been blocked. Contact your OpenMarket Account Manager to ensure that you are provisioned correctly.
Rejected	21	Campaign information is not provisioned for this mobile operator. Your campaign is identified in the MT configuration. In the US particularly, mobile operators may not accept messages that are not part of a campaign provisioned with them. Contact your OpenMarket Account Manager to ensure that you are provisioned correctly.
Rejected	22	OpenMarket cannot retrieve the MMS attachment from the URL as the attachment is too large.
Rejected	23	Failed to route message. OpenMarket cannot reach the specified mobile operator. This may occur in instances where the message is to a tier 3 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

You can test receiving most of the delivery reports sent by OpenMarket. See Testing Your MMS Integration.

Troubleshooting

I'm not receiving any delivery reports

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.