MMS API

MessageBird's MMS Messaging API enables you to send and receive MMS messages to and from a selected group of countries. Currently you can only send MMS within the US and Canada.

URI

https://rest.messagebird.com/mms

Messages are identified by a unique ID. And with this ID you can always check the status of the MMS message through the provided endpoint.

Available HTTP Methods

POST /mms
GET /mms
GET /mms/{messageId}
DELETE /mms/{messageId}

The MMS message object

This object represents an MMS message at MessageBird.com

Attributes

AttributeTypeDescription
idstringA unique ID which is created on the MessageBird platform and is returned upon creation of the object.
hrefstringThe URL of the created object.
directionstringTells you if the message is sent or received.
mt: mobile terminated (sent to mobile)
mo: mobile originated (received from mobile)
originatorstringThe sender/source address of the message. This has to be the dedicated MMS virtual mobile number (including country code) for either the US/CA.
recipientshashThe hash with recipient information. Further explanation in the table below.
subjectstringThe subject of the MMS message.
bodystringThe body of the MMS message.
mediaUrlsarrayAn array with URL's to the media attachments you want to send as part of the MMS message.
referencestringA client reference
scheduledDatetimedatetimeThe scheduled date and time of the message in RFC3339 format (Y-m-dTH:i:sP)
createdDatetimedatetimeThe date and time of the creation of the message in RFC3339 format (Y-m-dTH:i:sP)

Object example

{
"id": "efa6405d518d4c0c88cce11f7db775fb",
"href": "https://rest.messagebird.com/mms/efa6405d518d4c0c88cce11f7db775fb",
"direction": "mt",
"originator": "+31207009850",
"subject": "Great logo",
"body": "Hi! Please have a look at this very nice logo of this cool company.",
"reference": "the-customers-reference",
"mediaUrls": [
"https://www.messagebird.com/assets/images/og/messagebird.gif"
],
"scheduledDatetime": null,
"createdDatetime": "2017-09-01T10:00:00+00:00",
"recipients": {
"totalCount": 1,
"totalSentCount": 1,
"totalDeliveredCount": 0,
"totalDeliveryFailedCount": 0,
"items": [
{
"recipient": 31612345678,
"status": "sent",
"statusDatetime": "2017-09-01T10:00:00+00:00"
}
]
}
}

The recipients sub-object

AttributeTypeDescription
totalCountintegerThe total count of recipients.
totalSentCountintegerThe count of recipients that have the message pending (status sent, and buffered).
totalDeliveredCountintegerThe count of recipients where the message is delivered (status delivered).
totalDeliveryFailedCountintegerThe count of recipients where the delivery has failed (status delivery_failed).
itemsarrayAn array of recipient hashes
items[].recipientintegerThe msisdn of the recipient
items[].statusstringThe status of the message sent to the recipient. Possible values: scheduled, sent, buffered, delivered, expired, and delivery_failed
items[].statusDatetimedatetimeThe datum time of the last status in RFC3339 format (Y-m-dTH:i:sP)

View a message

This request retrieves the information of an existing sent MMS message. You only need to supply the unique message id that was returned upon creation.

Required parameters

ParameterTypeDescription
idstringThe message ID that has been returned upon creation of the object. Required

Definition

GET https://rest.messagebird.com/mms/{messageId}

Example request

curl -X GET https://rest.messagebird.com/mms/e8077d803532c0b5937c639b60216938 \ -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Returns

Returns an MMS message object if the request was successful and message has been found. If the request failed, an error object will be returned.

Example response

{
"id": "efa6405d518d4c0c88cce11f7db775fb",
"href": "https://rest.messagebird.com/mms/efa6405d518d4c0c88cce11f7db775fb",
"direction": "mt",
"originator": "YourName",
"subject": "Check out this cool MMS",
"body": "Have you seen this logo?",
"reference": null,
"mediaUrls": [
"https://www.messagebird.com/assets/images/og/messagebird.gif"
],
"scheduledDatetime": null,
"createdDatetime": "2017-09-01T10:00:00+00:00",
"recipients": {
"totalCount": 1,
"totalSentCount": 0,
"totalDeliveredCount": 1,
"totalDeliveryFailedCount": 0,
"items": [
{
"recipient": 31612345678,
"status": "delivered",
"statusDatetime": "2017-09-01T10:00:01+00:00"
}
]
}
}

Send an MMS message

This request creates a new MMS message object. MessageBird returns the created message object with each request. Per request, a max of 50 recipients can be entered.

Required parameters

ParameterTypeDescription
originatorstringThe sender of the message. This can be a telephone number (including country code - E.164) or an alphanumeric string. In case of an alphanumeric string, the maximum length is 11 characters. Required
recipientsarrayThe array of recipients MSISDNs, E.164 formatted. Required
bodystringThe body of the MMS message, UTF-8 encoded. Body or mediaUrls is required
mediaUrlsarrayArray of URL's of attachments of the MMS message. See media attachmentsfor more information about attachments. Body or mediaUrls is required

Optional parameters

ParameterTypeDescription
subjectstringThe subject of the MMS message, UTF-8 encoded
referencestringA client reference
scheduledDatetimedatetimeThe scheduled date and time of the message in RFC3339 format (Y-m-dTH:i:sP)

Definition

POST https://rest.messagebird.com/mms

Example request

curl -X POST https://rest.messagebird.com/mms \ -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \ -d "recipients=31612345678" \ -d "originator=YourName" \ -d "subject=Check out this cool MMS" \ -d "body=Have you seen this logo?" \ -d "mediaUrls[]=https://www.messagebird.com/assets/images/og/messagebird.gif"
Notification icon

Do note that values are not automatically urlencoded with the above example. Use `--data-urlencode` if you want to urlencode the values.

Returns

If successful, this request will return a message object. If the request failed, an error object will be returned.

Example response

curl -X POST https://rest.messagebird.com/mms \ -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \ -d "recipients=31612345678" \ -d "originator=YourName" \ -d "subject=Check out this cool MMS" \ -d "body=Have you seen this logo?" \ -d "mediaUrls[]=https://www.messagebird.com/assets/images/og/messagebird.gif"

Receive a message

The request to receive MMS MO (inbound) messages is a POST request from MessageBird to customer platform, and has the following POST parameters:

Parameters

AttributeTypeDescription
idstringA unique random UUID which is created on the MessageBird platform.
recipientstringThe recipient of the message (the VMN/long number).
originatorstringThe sender of the message.
bodystringThe body of the MMS message.
subjectstringThe subject of the MMS message.
mediaUrlsarrayAn array with URLs to the media attachments (max 10).
mediaContentTypesarrayAn array with the content/mime types of the attachments (same order/array index as mediaUrls).
createdDatetimestringThe date and time of the creation of the message in RFC3339 format (Y-m-dTH:i:sP).

Example request

POST id=a5f3ca18-2935-11e7-ad46-08002720e7b4&originator=1123456789&recipient=1987654321&subject=MMS+reply&body=View+our+logo&mediaUrls[0]=https://storage.googleapis.com/mms-assets/20170424/a0b40b77-30f8-4603-adf1-00be9321885b-messagebird.png&mediaContentTypes[0]=image/png&createdDatetime=2017-04-24T20:15:30+00:00

Handle a status report

Status reports are requests that are sent to your platform through a GET request. The requests hold information about the status of a message that you have sent through our API. Status reports are only provided for messages are sent to us with a reference and accounts that have configured their status report url.

attributes

AttributeTypeDescription
idstringThe message ID that is created by the MessageBird platform when the message is submitted, and returned upon creation of the object.
referencestringThe client reference that has been sent to API upon creation of the object.
recipientstringThe recipient where this status report applies to.
statusstringThe status of the message sent to the recipient. Possible values: scheduled, sent, buffered, delivered, expired, and delivery_failed
statusDatetimedatetimeThe datum time of this status in RFC3339 format (Y-m-dTH:i:sP)

Example request

GET http://your-own.url/script?id=efa6405d518d4c0c88cce11f7db775fb&reference=the-customers-reference&recipient=31612345678&status=delivered&statusDatetime=2017-09-01T10:00:05+00:00
GET http://your-own.url/script?id=efa6405d518d4c0c88cce11f7db775fb&reference=the-customers-reference&recipient=31612345678&status=delivered&statusDatetime=2017-09-01T10:00:05+00:00

Response

Your platform should respond with a 200 OK HTTP header. When our platform doesn't receive a 200 OK header, we will try to deliver the receipt again (up to 10 times, with increasing interval between requests).

Example response

200 OK

Media attachments

Limitations

  • An MMS message can carry up to 10 media attachments
  • MMS media URL should be public accessible and respond within 5 seconds
  • Maximum file size of an MMS media attachment is 1MB (1024KB)

Supported media types

The following media types are supported as MMS attachments.

MediaType
Audioaudio/basic
audio/L24
audio/mp4
audio/mpeg
audio/ogg
audio/vorbis
audio/vnd.rn-realaudio
audio/vnd.wave
audio/3gpp
audio/3gpp2
audio/ac3
audio/vnd.wave
audio/webm
audio/amr-nb
audio/amr
Videovideo/mpeg
video/mp4
video/quicktime
video/webm
video/3gpp
video/3gpp2
video/3gpp-tt
video/H261
video/H263
video/H263-1998
video/H263-2000
video/H264
Imageimage/jpeg
image/gif
image/png
image/bmp
Texttext/vcard
text/csv
text/rtf
text/richtext
text/calendar
Applicationapplication/pdf
cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings