MMS API

🚧

API Endpoint and Authentication

  • Your API endpoint varies based on where your imiconnect account is hosted. Visit Know Your API Endpoint section to know more.

  • You can use either Service Key or JSON Web Tokens (JWT) for authentication. If you use both JWT authentication and Service Key in an API request, JWT authentication takes priority, and the Service Key is ignored.

❗️

API Access

This API is currently available only for clients in the North American region.

When an MMS message is received via the Messaging API v2:

  • If the from senderID is not MMS enabled for the tenant in Admin Console, then the message is rejected.
  • If the senderID doesn't match the preset list, the API request fails with “Invalid senderID” response.

Request Body Parameters

ParameterDescription
channelMMS
fromThe number from which the MMS is sentThe from number can only be one of the MMS enabled numbers provisioned for the account
toThe number to which MMS is sentThe to number must follow E.164 format

Supported File Types and Sizes

The overall MMS size must not exceed 2 MB.

Media Type

File Extension

Maximum File Size

File

  • vcard
  • ical
  • pdf

1 MB

Overall MMS payload size

2 MB

Image

The URL must be publicly accessible and end with one of the following file types:

  • .bmp
  • .dib
  • .gif
  • .jpg
  • .jpeg
  • .png

2.9 MB with transcoding1 MB without transcoding

Audio

The URL must be publicly accessible and end with one of the following file types:

  • .3gp
  • .amr
  • .3ga
  • .m4a
  • .m4p
  • .m4b
  • .m4r
  • .mp3
  • .wav

9.75 MB with transcoding
1 MB without transcoding

Video

The URL must be publicly accessible and end with one of the following file types:

  • .3gp
  • .h263
  • .h264
  • .mp4
  • .m4v
97.5 MB with transcoding
1 MB without transcoding

HTTP Response Codes

HTTP Response CodesDescriptions
200 OKSuccessful
201 CreatedCreated
400 Bad RequestBad input parameter. Error description should indicate which one and why
401 UnauthorizedThe client passed in the invalid key/token
403 ForbiddenThe customer doesn’t exist. * Customer account over quota.
404 Not FoundResource not found
405 Method Not AllowedThe resource doesn't support the specified HTTP verb
409 ConflictConflict
429 Too Many RequestsToo many requests for rate limiting
500 Internal Server ErrorThe servers are not working as expected. The request is probably valid but needs to be requested again later
503 Service UnavailableService Unavailable

Delivery Receipts

{
    "deliveryInfoNotification": {
        "deliveryInfo": {
            "deliveryChannel": "mms",
            "Description": "Submitted",
            "destinationType": "msisdn",
            "timeStamp": "2016-07-21T12:44:23.644",
            "code": "7501",
            "deliveryStatus": "Submitted",
            "destination": "447500661610"
        },
        "correlationid": "3bd8edf31c81-4b72d8a2-290d-49e2-993e",
        "callbackData": "return callbackdata",
        "transid": "4b72d8a2-290d-49e2-993e-3bd8edf31c81"
    }
}
{
    "deliveryInfoNotification": {
        "deliveryInfo": {
            "deliveryChannel": "mms",
            "Description": "Delivered",
            "destinationType": "msisdn",
            "timeStamp": "2016-07-21T12:44:23.644",
            "code": "7500",
            "deliveryStatus": "Submitted",
            "destination": "447500661610"
        },
        "correlationid": "3bd8edf31c81-4b72d8a2-290d-49e2-993e",
        "callbackData": "return callbackdata",
        "transid": "4b72d8a2-290d-49e2-993e-3bd8edf31c81"
    }
}
{
    "deliveryInfoNotification": {
        "deliveryInfo": {
            "deliveryChannel": "mms",
            "Description": "Read",
            "destinationType": "msisdn",
            "timeStamp": "2016-07-21T12:44:23.644",
            "code": "7524",
            "deliveryStatus": "Read",
            "destination": "447500661610"
        },
        "correlationid": "3bd8edf31c81-4b72d8a2-290d-49e2-993e",
        "callbackData": "return callbackdata",
        "transid": "4b72d8a2-290d-49e2-993e-3bd8edf31c81"
    }
}
{
    "deliveryInfoNotification": {
        "deliveryInfo": {
            "deliveryChannel": "mms",
            "Description": "https://clientname.uk/offer|192.0.2.1",
            "destinationType": "msisdn",
            "timeStamp": "2016-07-21T12:44:23.644",
            "additionalInfo":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.90 Safari/537.36",
            "code": "7525",
            "deliveryStatus": "Clicked",
            "destination": "447500661610"
        },
        "correlationid": "3bd8edf31c81-4b72d8a2-290d-49e2-993e",
        "callbackData": "return callbackdata",
        "transid": "4b72d8a2-290d-49e2-993e-3bd8edf31c81"
    }
}
{
  "deliveryInfoNotification": {
    "deliveryInfo": {
      "deliveryChannel": "mms",
      "Description": "Message expired",
      "destinationType": "msisdn",
      "timeStamp": "2016-07-28T11:47:56.459Z",
      "code": "7208",
      "deliveryStatus": "Un-Delivered",
      "destination": "910000000001"
    },
    "correlationid": "",
    "callbackData": "",
    "transid": "8f0fd088-2a80-43e3-9da1-e82e52b17390"
  }
}

Status Codes

CodeMessageDelivery Status
7500DeliveredDelivered
7501SubmittedSubmitted
7208Un-deliveredMessage expired
7524OpenedOpened
7525Link|IPClicked
7552Address errorFailed
7553Address not foundFailed
7554Multimedia content refusedFailed
7555Message format corruptFailed
7556Message rejectedFailed

API Error Codes - HTTP 400 Bad Request

CodeMessage
7000Invalid JSON
7003Dynamic Format“Mandatory parameter missing: {{parameter}}”
7004Dynamic Format“Invalid parameter: {{parameter}}”
7127Source IP not whitelisted
7016Unknown exception
7020You have reached the maximum transaction limit
7101Invalid sender ID
7102Invalid destination address
7104Invalid app ID
7107Message length exceeded
7108Invalid template ID
7126Invalid content type
7009Maximum number of destinations reached
7022JSON size exceeded
Language
Click Try It! to start a request and see the response here!