Before You Begin

Building an MMS

This page explains more about the popular content types you can send via an MMS message and how to structure the mime body parts.

MMS technically allows any arbitrary file to be attached (much like email), and it is primarily down to the capabilities and behavior of each handset as to how the MMS is displayed. The following list isn't exhaustive and mobile operators and handsets may support more or less of the content types. When creating your MMS messaging services, we recommend testing the message against the mobile operators and handsets that are most popular in region or with your end users.

If you need further help, please contact OpenMarket support.

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.

Linking to external content (content caching)

One of the convenient things about using OpenMarket MMS is that you can link to externally-hosted content, which we then cache.

OpenMarket will cache any content that it retrieves from a URL for a limited amount of time. This reduces the bandwidth used and increases the speed at which you can send us message requests. To use this feature, you just need to store each content item externally, rather than include the content in the message request. All or part of the MMS message can use this feature (e.g., you could send text for the message and the SMIL in the message request, and supply URLs for the rest of the message).

Content type for the mime part

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

Content-Type: application/vnd.openmarket.remoteContent

For example:

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

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.

In the mime part, the other information you need to supply is the content-Id header and the file location. For example:

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

Text content

Text content is almost universally supported by handsets. Specify the following in the manifest:

Content-Type: text/plain; charset=(chosen character set)
Content-Id: (.txt filename)

For text content, we recommend using UTF-8 character encoding (charset=utf-8), and if you don’t specify charset then we assume that the character encoding is UTF-8. However, you can use other character encodings such as ascii, iso-8859-15, and iso-8859-1.

Here is an example text mime part:

--mimeboundary
Content-Type: text/plain; charset=utf-8
Content-Id: example.txt 
This is my text.
--mimeboundary

The text data and encoding information is passed to each mobile operator without modification. However, some mobile operators may transcode the text data before delivering to handsets.

Images

Standard image formats of JPEG, GIF, and PNG are supported by the majority of handsets. We recommend using just these image formats. Specify the following in the manifest:

Content-Type: image/(png, jpg, gif)
Content-Id: (.png, .jpg, .gif filename)
Content-Transfer-Encoding: (BASE64 or BINARY)

If you don’t specify the Content-Transfer-Encoding, then we assume that it is BINARY.

Here is a working example of a mime-part that sends a .png file.

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

Video

Support for video is mixed between handsets. The most widely supported way to deliver video is using an MP4 container (video/mp4) with H264 video and AAC audio. This works on iPhones and the majority of Android phones. Specify the following in the manifest:

Content-Type: video/(mp4)
Content-Id: (.mp4 filename)
Content-Transfer-Encoding: (BASE64 or BINARY)

If you don’t specify the Content-Transfer-Encoding, then we assume that it is BINARY.

Here is an example mime part for a video file.

--mimeboundary
Content-Type: video/mp4
Content-Id: example-video.mp4
Content-Transfer-Encoding: BASE64 
iVBORw0KGgoAAAANS…
--mimeboundary

SMIL files

SMIL files are optional XML markup files that tell a handset how to present the contents of an MMS message. It pieces together the MMS files into the order that the end user sees, and combines them into a single stream so that the message display is properly time coordinated and synchronized. If you are using a SMIL file to describe how the MMS should flow, then the order does not matter.

If you want to reference an attachment inside a SMIL file, refer to the attachment directly and without angle brackets; e.g. img src="contentid" region="Image".

For anything more than plain ASCII characters encode using UTF-8 and make sure that the content type is set to application/smil; charset="UTF-8".

PDFs

PDFs (application/pdf) work on iPhones and Android. The end user will need a PDF reader installed. Use the Content-Type: application/pdf. For example:

--mimeboundary
Content-Type: application/pdf
Content-Id: map.pdf
Content-Transfer-Encoding: BASE64 
iVBORw0KGgoAAAANS…
--mimeboundary

Passbook

You can send Passbook files to iPhones via MMS. Use the Content-Type: application/vnd.apple.pkpass. For example:

--mimeboundary
Content-Type: application/vnd.apple.pkpass
Content-Id: mypassbook.pkpass
Content-Transfer-Encoding: BASE64 
iVBORw0KGgoAAAANS…
--mimeboundary

vCards

Support for vCards via MMS is limited:

For iPhones, you can send vCard files as long as the content ID ends with .vcf.
Some feature phones will accept vCards
Most Android phones don't accept vCards via MMS

Use the Content-Type: text/vcard and specify the character encoding. For example:

--mimeboundary
Content-Type: text/vcard; charset=utf-8
Content-Id: contacts.vcf 
BEGIN:VCARD
VERSION:2.1
N:Claus;Santa
FN:Santa Claus
ORG:Christmas and Co.
TITLE:CEO
PHOTO;GIF:http://www.example.com/dir_photos/my_photo.gif
TEL;WORK;VOICE:(111) 555-1212
TEL;HOME;VOICE:(404) 555-1212
ADR;HOME:;;101 Santa Lane;North Pole;Arctic Circle;12345;Planet Earth
LABEL;HOME;ENCODING=QUOTED-PRINTABLE: 101 Santa Lane.=0D=0ANorth Pole, Arctic Circle 12345=0D=0APlanet Earth
EMAIL;PREF;INTERNET:santaclaus@thenorthpole.com
REV:20080424T195243Z
END:VCARD
--mimeboundary