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

Parameter

Description

channel

MMS

from

The number from which the MMS is sent

The from number can only be one of the MMS enabled numbers provisioned for the account

to

The number to which MMS is sent

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

Descriptions

200 OK

Successful

201 Created

Created

400 Bad Request

Bad input parameter. Error description should indicate which one and why

401 Unauthorized

The client passed in the invalid key/token

403 Forbidden

The customer doesn’t exist. * Customer account over quota.

404 Not Found

Resource not found

405 Method Not Allowed

The resource doesn't support the specified HTTP verb

409 Conflict

Conflict

429 Too Many Requests

Too many requests for rate limiting

500 Internal Server Error

The servers are not working as expected. The request is probably valid but needs to be requested again later

503 Service Unavailable

Service 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

Code

Message

Delivery Status

7500

Delivered

Delivered

7501

Submitted

Submitted

7208

Un-delivered

Message expired

7524

Opened

Opened

7525

Link|IP

Clicked

7552

Address error

Failed

7553

Address not found

Failed

7554

Multimedia content refused

Failed

7555

Message format corrupt

Failed

7556

Message rejected

Failed

API Error Codes - HTTP 400 Bad Request

Code

Message

7000

Invalid JSON

7003

Dynamic Format

“Mandatory parameter missing: {{parameter}}”

7004

Dynamic Format

“Invalid parameter: {{parameter}}”

7127

Source IP not whitelisted

7016

Unknown exception

7020

You have reached the maximum transaction limit

7101

Invalid sender ID

7102

Invalid destination address

7104

Invalid app ID

7107

Message length exceeded

7108

Invalid template ID

7126

Invalid content type

7009

Maximum number of destinations reached

7022

JSON size exceeded

Language
Click Try It! to start a request and see the response here!