post https://api.imiconnect.io/v2/messages
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 sentThe from number can only be one of the MMS enabled numbers provisioned for the account |
| to | The 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 |
| 1 MB |
Overall MMS payload size | 2 MB | |
Image | The URL must be publicly accessible and end with one of the following file types:
| 2.9 MB with transcoding1 MB without transcoding |
Audio | The URL must be publicly accessible and end with one of the following file types:
| 9.75 MB with transcoding |
Video | The URL must be publicly accessible and end with one of the following file types:
| 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 |