API Reference

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

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.

The MMS API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization framework. Request and response payloads are formatted as JSON—although we provide a GET alternative for requests—using UTF-8 encoding and URL encoded values.

Keep in mind that sending and receiving MMS is only possible if the VMN is MMS enabled. .

API Endpoint

All URLs referenced in MessageBird's MMS API documentation have the base URL in the code snippet on the right side:

URI

https://rest.messagebird.com/mms

Available HTTP methods

The MessageBird API uses HTTP verbs to understand if you want to read (GET), delete (DELETE) or create (POST) an object. When your web application cannot do a POST or DELETE, we provide the ability to set the method through the query parameter _method.

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

Attribute	Type	Description
id	string	A unique ID which is created on the MessageBird platform and is returned upon creation of the object.
href	string	The URL of the created object.
direction	string	Tells you if the message is sent or received. mt: mobile terminated (sent to mobile) mo: mobile originated (received from mobile)
originator	string	The sender/source address of the message. This has to be the dedicated MMS virtual mobile number (including country code) for either the US/CA.
recipients	hash	The hash with recipient information. Further explanation in the table below.
subject	string	The subject of the MMS message. Character limit: 256.
body	string	The body of the MMS message. Character limit: 2000.
mediaUrls	array	An array with URL's to the media attachments you want to send as part of the MMS message.
reference	string	A client reference
scheduledDatetime	datetime	The scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP)
createdDatetime	datetime	The date and time of the creation of the message in RFC3339 format (Y-m-d\TH: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://developers.messagebird.com/img/logos/mb-400.jpg"
  ],
  "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

Attribute	Type	Description
totalCount	integer	The total count of recipients.
totalSentCount	integer	The count of recipients that have the message pending (status sent, and buffered).
totalDeliveredCount	integer	The count of recipients where the message is delivered (status delivered).
totalDeliveryFailedCount	integer	The count of recipients where the delivery has failed (status delivery_failed).
items	array	An array of recipient hashes
items[].recipient	integer	The msisdn of the recipient
items[].status	string	The status of the message sent to the recipient. Possible values: scheduled, sent, buffered, delivered, expired, and delivery_failed
items[].statusDatetime	datetime	The datum time of the last status in RFC3339 format (Y-m-d\TH: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

Parameter	Type	Description
id	string	The 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://developers.messagebird.com/img/logos/mb-400.jpg"
  ],
  "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

Parameter	Type	Description
originator	string	The 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
recipients	array	The array of recipients MSISDNs, E.164 formatted. Required
body	string	The body of the MMS message, UTF-8 encoded. Body or mediaUrls is required
mediaUrls	array	Array of URL's of attachments of the MMS message. See media attachmentsfor more information about attachments. Body or mediaUrls is required

Optional parameters

Parameter	Type	Description
subject	string	The subject of the MMS message, UTF-8 encoded
reference	string	A client reference
scheduledDatetime	datetime	The scheduled date and time of the message in RFC3339 format (Y-m-d\TH: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://developers.messagebird.com/img/logos/mb-400.jpg"

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

{
  "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://developers.messagebird.com/img/logos/mb-400.jpg"
  ],
  "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"
      }
    ]
  }
}

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

Attribute	Type	Description
id	string	A unique random UUID which is created on the MessageBird platform.
recipient	string	The recipient of the message (the VMN/long number).
originator	string	The sender of the message.
body	string	The body of the MMS message.
subject	string	The subject of the MMS message.
mediaUrls	array	An array with URLs to the media attachments (max 10).
mediaContentTypes	array	An array with the content/mime types of the attachments (same order/array index as mediaUrls).
createdDatetime	string	The date and time of the creation of the message in RFC3339 format (Y-m-d\TH: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

Attribute	Type	Description
id	string	The message ID that is created by the MessageBird platform when the message is submitted, and returned upon creation of the object.
reference	string	The client reference that has been sent to API upon creation of the object.
recipient	string	The recipient where this status report applies to.
status	string	The status of the message sent to the recipient. Possible values: scheduled, sent, buffered, delivered, expired, and delivery_failed
statusDatetime	datetime	The datum time of this status in RFC3339 format (Y-m-d\TH: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.

Media	Type
Audio	audio/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
Video	video/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
Image	image/jpeg image/gif image/png image/bmp
Text	text/vcard text/csv text/rtf text/richtext text/calendar
Application	application/pdf

Is this page useful?

Next upHlr

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings