Things to Know

Before using HTTP MMS, familiarize yourself with how it works:

• Connecting to OpenMarket
• Authenticating
• Flow for receiving an MO MMS delivery

Connecting to OpenMarket

For most customer scenarios, the simplest HTTPS endpoint to use to reach our data centers is:

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

Requests submitted to this endpoint are routed to the closest data center. If the data center becomes unavailable then messages are automatically routed to the next closest data center. This provides your service with a high available data strategy without requiring additional setup. However, you will need to ensure that your systems only cache the DNS lookup for up to one minute.

Direct data center connections

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

For data center one:

https://mmsc-01.openmarket.com

https://mmsc-02.openmarket.com

For data center two:

https://mmsc-03.openmarket.com

https://mmsc-04.openmarket.com

If desired, you can establish parallel connections to the data center using these connections.

Authenticating

To authenticate with OpenMarket, include your OpenMarket account ID and password in the request header using Basic authentication.

Flow for sending an MT MMS and receiving a delivery report

The following shows how to successfully send an MT MMS and receive delivery reports back from OpenMarket.

Steps:

1. Your system sends an HTTPS POST request for the MT MMS message.
   You can deliver the contents of the MMS message as MIME content parts inside request and as links to content. Use links to content if you want to take advantage of caching. For example, this request specifies a MP4 file OpenMarket will cache:

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   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": "",
      "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
   

2. OpenMarket sends back an HTTPS 200 response. The response body includes an mtId, which uniquely identifies the MMS message in our systems.

   Copy

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

3. OpenMarket delivers the message to the mobile operator.
4. After delivering the message successfully, the mobile operator returns a delivery report.
   
   Note that sometimes we may not receive a report back, even when the end user's handset successfully received the message.

5. OpenMarket sends a delivery report to your system, with the mtId in the request body and a delivery report status that confirms successful (or unsuccessful) message delivery.

   Copy

   POST /exampleEndpoint HTTP/1.1
   Host: example.com
   X-Request-Id: 015-3DD6C366-D68A-4A02-9777-19CBC8AB40C1
   Content-Type: application/json 
   {
      "type": "REPORT",
      "mtId": 123456789012345,
      "date": "2016-05-16T19:20:30+00:00",
      "status": "Retrieved",
      "outcomeId": 1,
      "outcomeDescription": "Success.",
      "userAgent": "HTC One"
   }

6. Your system sends back an HTTPS 200 response.

Flow for receiving an MO MMS delivery

The following shows how to successfully receive an MO MMS from OpenMarket.

Steps:

1. The mobile operator delivers an MMS message for your short code (US and UK), toll-free, text-enabled number (US only), or virtual mobile number (UK only).

2. OpenMarket sends an HTTPS POST request to your system. The MMS content is sent in MIME multipart in the request body. An moId is also included that uniquely identifies the request in OpenMarket's systems.

   Copy

   POST /customerEndpoint HTTP/1.1
   Host: example.com
   X-Request-Id: 015-3DD6C366-D68A-4A02-9777-19CBC8AB40C1
   Content-Type: multipart/mixed; boundary=mimeboundary 
   --mimeboundaryContent-Type: application/json
   Content-Id: main 
   {
      "type": "MO",
      "destinations": ["88600"],
      "ccs": [], 
      "bccs": [], 
      "source": "14553011955",
      "subject": "Norwegian Blue",
      "moId": 123456789012345,
      "mobileOperatorId": 77,
      "date": "2021-06-02T17:14:26+00:00",
      "userAgent": "HTC One"
   }
   --mimeboundary
   Content-Type: text/plain
   Content-Id: text.txt 
   Here is a picture of the bird in question
   --mimeboundary--

3. Your system sends back an HTTPS 200 response.