Intelligent Messaging API v0.0.1
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
This is the Intelligent Messaging API for sending messages with automated fallback to other delivery channels.
Base URLs:
Terms of service Email: API Support Web: API Support License: Modica API - Terms Of Use
Authentication
- API Key (gateway_auth)
- Parameter Name: authorization, in: header. A custom authorizer for the im-api service.
messages
Messaging endpoints.
message_post
Code samples
# You can also use wget
curl -X POST https://api.modicagroup.com/rest/im/v1/message \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'authorization: API_KEY'
POST https://api.modicagroup.com/rest/im/v1/message HTTP/1.1
Host: api.modicagroup.com
Content-Type: application/json
Accept: application/json
const inputBody = '{
"destination": {
"contact_id": "stringstringstringstringstringstring",
"mobile": "string",
"email": "user@example.com"
},
"source": {
"source_id": "stringstringstringstringstringstring",
"channel_sources": [
{
"channel": "email",
"source": "im-email@modicagroup.com"
}
]
},
"message": {
"type": "text",
"text": {
"subject": "string",
"body": "string"
},
"media": {
"type": "image/png",
"url": "https://www.luckyshrub.com/assets/succulents/aloe.png"
},
"template": {
"template_id": "otp_wab_template"
}
},
"delivery_attempts": [
{
"firstdeliveryattempt": {
"channel": "wab",
"event": "read",
"timeout": 15
}
}
],
"reference": "string",
"mask": "string",
"charset": "ASCII",
"expires": "2026-11-05T10:00:00+13:00"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'authorization':'API_KEY'
};
fetch('https://api.modicagroup.com/rest/im/v1/message',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
const fetch = require('node-fetch');
const inputBody = {
"destination": {
"contact_id": "stringstringstringstringstringstring",
"mobile": "string",
"email": "user@example.com"
},
"source": {
"source_id": "stringstringstringstringstringstring",
"channel_sources": [
{
"channel": "email",
"source": "im-email@modicagroup.com"
}
]
},
"message": {
"type": "text",
"text": {
"subject": "string",
"body": "string"
},
"media": {
"type": "image/png",
"url": "https://www.luckyshrub.com/assets/succulents/aloe.png"
},
"template": {
"template_id": "otp_wab_template"
}
},
"delivery_attempts": [
{
"firstdeliveryattempt": {
"channel": "wab",
"event": "read",
"timeout": 15
}
}
],
"reference": "string",
"mask": "string",
"charset": "ASCII",
"expires": "2026-11-05T10:00:00+13:00"
};
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'authorization':'API_KEY'
};
fetch('https://api.modicagroup.com/rest/im/v1/message',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'authorization' => 'API_KEY'
}
result = RestClient.post 'https://api.modicagroup.com/rest/im/v1/message',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'authorization': 'API_KEY'
}
r = requests.post('https://api.modicagroup.com/rest/im/v1/message', headers = headers)
print(r.json())
URL obj = new URL("https://api.modicagroup.com/rest/im/v1/message");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"authorization": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.modicagroup.com/rest/im/v1/message", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
'application/json',
'Accept' => 'application/json',
'authorization' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.modicagroup.com/rest/im/v1/message', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
POST /message
Send a message with automated fallback to other delivery channels.
Send a message with automated fallback to other delivery channels.
Body parameter
{
"destination": {
"contact_id": "stringstringstringstringstringstring",
"mobile": "string",
"email": "user@example.com"
},
"source": {
"source_id": "stringstringstringstringstringstring",
"channel_sources": [
{
"channel": "email",
"source": "im-email@modicagroup.com"
}
]
},
"message": {
"type": "text",
"text": {
"subject": "string",
"body": "string"
},
"media": {
"type": "image/png",
"url": "https://www.luckyshrub.com/assets/succulents/aloe.png"
},
"template": {
"template_id": "otp_wab_template"
}
},
"delivery_attempts": [
{
"firstdeliveryattempt": {
"channel": "wab",
"event": "read",
"timeout": 15
}
}
],
"reference": "string",
"mask": "string",
"charset": "ASCII",
"expires": "2026-11-05T10:00:00+13:00"
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | MessagePostRequest | false | none |
Example responses
202 Response
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
400 Response
{
"message": "API bad request error",
"statusCode": 400,
"error": "bad request error message"
}
401 Response
{
"message": "API unauthorized error",
"statusCode": 401,
"error": "unauthorized error message"
}
404 Response
{
"message": "API not found error",
"statusCode": 404,
"error": "not found error message"
}
422 Response
{
"message": "Validation failed",
"errors": [
{
"field": "delivery_attempts.0.timeout",
"description": "timeout must not be empty"
}
]
}
429 Response
{
"message": "API too many requests error",
"statusCode": 429,
"error": "too many requests error message"
}
500 Response
{
"message": "API internal server error",
"statusCode": 500,
"error": "internal server error message"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 202 | Accepted | Successful Post Message response structure. | Inline |
| 400 | Bad Request | Invalid request data. This response is returned when the request data is invalid or improperly formatted. | APIError |
| 401 | Unauthorized | Unauthorized. This response is returned when the user is not authorized to perform the requested action. | APIError |
| 404 | Not Found | Not Found. This response indicates that the requested resource was not found. | APIError |
| 422 | Unprocessable Entity | Unprocessable Entity. This response is returned when the request data is correct but cannot be processed. | APIError |
| 429 | Too Many Requests | Too Many Requests. This response indicates that the client has exceeded the rate limits. | APIError |
| 500 | Internal Server Error | Internal server error. This response is returned when an internal server error occurs. | APIError |
Response Schema
Status Code 202
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » id | Uuid | false | none | A random UUID - version 4. |
Callbacks
messageCallback
{$statusCallbackUrl}
message_post
Code samples
# You can also use wget
curl -X POST https://api.modicagroup.com/rest/im/v1/message \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'authorization: API_KEY'
POST https://api.modicagroup.com/rest/im/v1/message HTTP/1.1
Host: api.modicagroup.com
Content-Type: application/json
Accept: application/json
const inputBody = '{
"id": "2af85f64-3645-1078-b3fc-2c963f66afa6",
"reference": "ref-abc123",
"channel": "sms",
"status": "received"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'authorization':'API_KEY'
};
fetch('https://api.modicagroup.com/rest/im/v1/message',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
const fetch = require('node-fetch');
const inputBody = {
"id": "2af85f64-3645-1078-b3fc-2c963f66afa6",
"reference": "ref-abc123",
"channel": "sms",
"status": "received"
};
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'authorization':'API_KEY'
};
fetch('https://api.modicagroup.com/rest/im/v1/message',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'authorization' => 'API_KEY'
}
result = RestClient.post 'https://api.modicagroup.com/rest/im/v1/message',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'authorization': 'API_KEY'
}
r = requests.post('https://api.modicagroup.com/rest/im/v1/message', headers = headers)
print(r.json())
URL obj = new URL("https://api.modicagroup.com/rest/im/v1/message");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"authorization": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.modicagroup.com/rest/im/v1/message", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
'application/json',
'Accept' => 'application/json',
'authorization' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.modicagroup.com/rest/im/v1/message', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
POST /message
Status/DLR callback
Sent when the status of a MT message is updated
Body parameter
{
"id": "2af85f64-3645-1078-b3fc-2c963f66afa6",
"reference": "ref-abc123",
"channel": "sms",
"status": "received"
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | StatusCallback | false | Status callback payload |
Example responses
401 Response
{
"message": "API unauthorized error",
"statusCode": 401,
"error": "unauthorized error message"
}
429 Response
{
"message": "API too many requests error",
"statusCode": 429,
"error": "too many requests error message"
}
500 Response
{
"message": "API internal server error",
"statusCode": 500,
"error": "internal server error message"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | callback successfully processed | None |
| 401 | Unauthorized | Unauthorized. This response is returned when the user is not authorized to perform the requested action. | APIError |
| 429 | Too Many Requests | Too Many Requests. This response indicates that the client has exceeded the rate limits. | APIError |
| 500 | Internal Server Error | Internal server error. This response is returned when an internal server error occurs. | APIError |
Response Headers
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-RateLimit-Limit | integer | int32 | Requests per second limit. |
Schemas
Charset
"ASCII"
The charset for the email message content.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | string | false | none | The charset for the email message content. |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | ASCII |
| anonymous | UTF-8 |
| anonymous | ISO-8859-1 |
| anonymous | Shift_JIS |
MessagePostRequest
{
"destination": {
"contact_id": "stringstringstringstringstringstring",
"mobile": "string",
"email": "user@example.com"
},
"source": {
"source_id": "stringstringstringstringstringstring",
"channel_sources": [
{
"channel": "email",
"source": "im-email@modicagroup.com"
}
]
},
"message": {
"type": "text",
"text": {
"subject": "string",
"body": "string"
},
"media": {
"type": "image/png",
"url": "https://www.luckyshrub.com/assets/succulents/aloe.png"
},
"template": {
"template_id": "otp_wab_template"
}
},
"delivery_attempts": [
{
"firstdeliveryattempt": {
"channel": "wab",
"event": "read",
"timeout": 15
}
}
],
"reference": "string",
"mask": "string",
"charset": "ASCII",
"expires": "2026-11-05T10:00:00+13:00"
}
Message Send Request
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| destination | Destination | true | none | A destination for the message. |
| source | Source | false | none | The sender to use for each channel. If a channel has no source, the default sender configured for your application is used. |
| message | Message | true | none | none |
| delivery_attempts | [DeliveryAttempt] | false | none | [Sequence of channel delivery attempts.] |
| reference | string(none) | false | none | Your own reference for the message. It is returned in status callbacks. |
| mask | string | false | none | A sender mask to apply to the message. |
| charset | Charset | false | none | The charset for the email message content. |
| expires | string(date-time) | false | none | The time after which the message should no longer be delivered, in RFC 3339 format. |
Destination
{
"contact_id": "stringstringstringstringstringstring",
"mobile": "string",
"email": "user@example.com"
}
Destination
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| contact_id | Uuid | false | none | A random UUID - version 4. |
| mobile | E164 | false | none | The destination number in E.164 format. |
| false | none | An email address. |
Source
{
"source_id": "stringstringstringstringstringstring",
"channel_sources": [
{
"channel": "email",
"source": "im-email@modicagroup.com"
}
]
}
Source
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| source_id | Uuid | false | none | A random UUID - version 4. |
| channel_sources | [ChannelSource] | false | none | [The source for this channel.] |
ChannelSource
{
"channel": "email",
"source": "im-email@modicagroup.com"
}
The source for this channel.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| channel | Channel | true | none | none |
| source | string | true | none | For sms, an E.164 number or a short code. For wab, a WhatsApp Business phone number ID. For email, the sender email address. |
Message
{
"type": "text",
"text": {
"subject": "string",
"body": "string"
},
"media": {
"type": "image/png",
"url": "https://www.luckyshrub.com/assets/succulents/aloe.png"
},
"template": {
"template_id": "otp_wab_template"
}
}
Message
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | MessageType | true | none | none |
| text | TextMessage | false | none | none |
| media | MediaMessage | false | none | none |
| template | TemplateMessage | false | none | none |
TextMessage
{
"subject": "string",
"body": "string"
}
Content of a Text message.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| subject | ShortString | false | none | The email subject. Used by the email channel only. |
| body | LongString | true | none | A generic long string format. |
MediaMessage
{
"type": "image/png",
"url": "https://www.luckyshrub.com/assets/succulents/aloe.png"
}
Content of a Media message.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | MimeType | true | none | none |
| url | Url | true | none | none |
TemplateMessage
{
"template_id": "otp_wab_template"
}
Content of a Template message.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| template_id | Uuid | true | none | A random UUID - version 4. |
| language | string | false | none | none |
| parameters | [TemplateParameter] | false | none | [The text value that will replace the parameter in the template.] |
TemplateParameter
{
"name": "otp_code",
"text": "458972"
}
The text value that will replace the parameter in the template.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | ShortString | true | none | Name of the template parameter. |
| text | string(none) | true | none | Value of the template parameter. |
DeliveryAttempt
{
"firstdeliveryattempt": {
"channel": "wab",
"event": "read",
"timeout": 15
}
}
Sequence of channel delivery attempts.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| channel | Channel | true | none | none |
| event | ShortString | false | none | The status that counts as a successful delivery for this attempt, such as received or read. Required on every attempt except the last. |
| timeout | integer(int32) | false | none | How long to wait for the event, in seconds, before trying the next attempt. Required on every attempt except the last. |
Channel
"wab"
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | string | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | wab |
| anonymous | sms |
| anonymous | mms |
| anonymous | |
| anonymous | rcs |
MessageType
"text"
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | string | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | text |
| anonymous | media |
| anonymous | template |
MimeType
"string"
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | string | false | none | none |
E164
"string"
The destination number in E.164 format.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | string | false | none | The destination number in E.164 format. |
APIError
{
"code": 200,
"message": "string",
"errors": [
{
"field": "string",
"code": 200,
"description": "string"
}
]
}
APIError
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| code | integer(int32) | false | none | none |
| message | LongString | false | none | A generic long string format. |
| errors | [Error] | false | none | [A generic error object.] |
Error
{
"field": "string",
"code": 200,
"description": "string"
}
Error
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| field | ShortString | false | none | A generic short string format. |
| code | integer(int64) | false | none | none |
| description | LongString | true | none | A generic long string format. |
LongString
"string"
A generic long string format.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | string | false | none | A generic long string format. |
ShortString
"string"
A generic short string format.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | string | false | none | A generic short string format. |
Url
"string"
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | string(url) | false | none | none |
Uuid
"stringstringstringstringstringstring"
A random UUID - version 4.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | string | false | none | A random UUID - version 4. |
"user@example.com"
An email address.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | string(email) | false | none | An email address. |
StatusCallback
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"detail": "string",
"reference": "string",
"channel": "wab",
"status": "accepted"
}
Status callback structure.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string(uuid) | false | none | none |
| detail | string(none) | false | none | none |
| reference | string | false | none | The reference supplied when the message was sent, if any. |
| channel | Channel | false | none | The delivery channel this status relates to. Omitted for statuses about the message as a whole. |
| status | string | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| status | accepted |
| status | submitted |
| status | sent |
| status | received |
| status | read |
| status | frozen |
| status | rejected |
| status | failed |
| status | dead |
| status | expired |