IM API
When to choose IM API
Choose IM API when one request needs to manage delivery across multiple channels with fallback rules, such as trying WhatsApp first and then SMS; choose a single-channel API when your integration only needs to send through one known channel.
Overview
Modica’s Intelligent Messaging API provides automatic fallback to alternative delivery channels (SMS, WhatsApp, email, etc…).
A fallback can be triggered by a specific event (and a timeout).
Example: fallback to sending the message as SMS if the WhatsApp message fails to be delivered within 10 seconds.
What the API can do
- Send a message request to the Intelligent Messaging endpoint
- Deliver through the default SMS channel when no delivery attempts are specified
- Try up to 10 channels in order, such as WhatsApp Business, then SMS, then email
- Trigger fallback based on delivery events and timeout values of up to 7 days
- Send text messages or pre-defined template messages
- Send email with a subject line and a choice of character set
- Apply a sender mask
- Set an expiry time after which the message is no longer delivered
- Attach your own reference, returned to you in status callbacks
- Receive status callbacks for the message and for each delivery attempt
- Include a correlation ID so your application can trace requests end to end
How it works
In practice, the API follows a simple workflow:
- Authenticate with your IM API credentials.
- Submit a message request to
/message. - Include the destination, message body or template, and optional delivery attempts.
- If delivery attempts are provided, the API tries each channel in order.
- If a configured event is not reached within the timeout, the API falls back to the next channel.
When to use IM API
Use IM API when your application needs channel orchestration rather than a fixed SMS-only or WhatsApp-only workflow. It is useful for customer notifications where WhatsApp may be preferred, but SMS should be used if the WhatsApp message is not received or read within a defined time.
If your application always sends through one channel, use that channel’s API directly. For SMS-only workflows, review REST v2 or REST v1. For WhatsApp-only workflows, review the WhatsApp for Business API.
Before you start
Before making your first request, confirm the following:
- Your IM API application has been provisioned.
- You have the application name and password for HTTP Basic Authentication.
- Your sending server IP address is authorised if IP allowlisting is enabled.
- The recipient mobile number is in international format.
- Any WhatsApp templates used in template messages are already configured and approved.
- If you send by email, your sender email address has been set up for your application.
- If you want delivery updates, your status callback URL is configured.
First successful request path
For most implementations, the fastest way to validate connectivity and configuration is:
- Authenticate using your IM API credentials.
- Submit a simple POST request to
/messagewith a mobile destination and text body. - Confirm the
202response and store the returned message ID. - Add delivery attempts after the simple SMS request succeeds.
- Test the fallback path by sending a WhatsApp Business attempt followed by SMS.
Authentication
HTTP Basic Authentication is used for all requests. If you access the API without having the correct credentials OR permission to access the API, you will get a HTTP 401 response.
Your gateway application credentials (application name and password) are available on the IM API configuration page in Modica.
You will need a user account and password to retrieve these.
If you don’t have these details, please contact support@modicagroup.com.
Authorised IP Addresses
You can whitelist your servers’ IPs or IP ranges using the ‘Add IP Address’ button under “Authorised IP Addresses”
Please note: once one or more IP addresses or IP ranges have been added connections from all other IP addresses will be rejected, any attempt from an IP not in the list will receive an Authentication error.
Base URI
All API access is over HTTPS, and accessed from:
https://api.modicagroup.com/rest/im/v1
Versions
The IM API version is currently v1.
OpenAPI Specification
This API has been developed in accordance with the OpenAPI specification defined here.
The OpenAPI (Swagger) specification can be found here: here.
You can see code examples and further information here.
Sending Intelligent Messages
You can send an IM message to the following endpoints using the cURL utility.
Send a simple IM message as SMS
curl -X POST 'https://api.modicagroup.com/rest/im/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <TOKEN>' \
-d '{
"destination": {
"mobile": "+64272383189"
},
"message": {
"type": "text",
"text": {
"body": "My SMS content"
}
}
}'
const response = await fetch("https://api.modicagroup.com/rest/im/v1/message", {
method: "POST",
headers: {
"Authorization": "Basic <TOKEN>",
"Content-Type": "application/json"
},
body: JSON.stringify({
destination: {
mobile: "+64272383189"
},
message: {
type: "text",
text: {
body: "My SMS content"
}
}
})
});
const result = await response.json();import requests
response = requests.post(
"https://api.modicagroup.com/rest/im/v1/message",
headers={
"Authorization": "Basic <TOKEN>",
"Content-Type": "application/json",
},
json={
"destination": {
"mobile": "+64272383189",
},
"message": {
"type": "text",
"text": {
"body": "My SMS content",
},
},
},
)
result = response.json()<?php
$payload = json_encode([
"destination" => [
"mobile" => "+64272383189"
],
"message" => [
"type" => "text",
"text" => [
"body" => "My SMS content"
]
]
]);
$ch = curl_init("https://api.modicagroup.com/rest/im/v1/message");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Basic <TOKEN>",
"Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
require "json"
require "net/http"
require "uri"
uri = URI("https://api.modicagroup.com/rest/im/v1/message")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Basic <TOKEN>"
request["Content-Type"] = "application/json"
request.body = {
destination: {
mobile: "+64272383189"
},
message: {
type: "text",
text: {
body: "My SMS content"
}
}
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
endimport java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
String payload = """
{
"destination": {
"mobile": "+64272383189"
},
"message": {
"type": "text",
"text": {
"body": "My SMS content"
}
}
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.modicagroup.com/rest/im/v1/message"))
.header("Authorization", "Basic <TOKEN>")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());using System.Text;
using var client = new HttpClient();
var request = new HttpRequestMessage(
HttpMethod.Post,
"https://api.modicagroup.com/rest/im/v1/message");
request.Headers.TryAddWithoutValidation("Authorization", "Basic <TOKEN>");
request.Content = new StringContent(
"""{"destination":{"mobile":"+64272383189"},"message":{"type":"text","text":{"body":"My SMS content"}}}""",
Encoding.UTF8,
"application/json");
var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();Note: if no delivery_attempts field is provided, the delivery channel defaults to sms.
202 response:
{
"id": "b95fc11e-37f0-4770-a082-6ea22d4c4d12"
}
The id identifies the message in every status callback. See Errors for failed requests.
Send a simple IM message as WAB with fallback to SMS after 10 seconds
curl -X POST 'https://api.modicagroup.com/rest/im/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <TOKEN>' \
-d '{
"destination": {
"mobile": "+64272383189"
},
"message": {
"type": "text",
"text": {
"body": "Test"
}
},
"delivery_attempts": [
{
"channel": "wab",
"event": "received",
"timeout": 10
},
{
"channel": "sms"
}
]
}'
const response = await fetch("https://api.modicagroup.com/rest/im/v1/message", {
method: "POST",
headers: {
"Authorization": "Basic <TOKEN>",
"Content-Type": "application/json"
},
body: JSON.stringify({
destination: {
mobile: "+64272383189"
},
message: {
type: "text",
text: {
body: "Test"
}
},
delivery_attempts: [
{
channel: "wab",
event: "received",
timeout: 10
},
{
channel: "sms"
}
]
})
});
const result = await response.json();import requests
response = requests.post(
"https://api.modicagroup.com/rest/im/v1/message",
headers={
"Authorization": "Basic <TOKEN>",
"Content-Type": "application/json",
},
json={
"destination": {
"mobile": "+64272383189",
},
"message": {
"type": "text",
"text": {
"body": "Test",
},
},
"delivery_attempts": [
{
"channel": "wab",
"event": "received",
"timeout": 10,
},
{
"channel": "sms",
},
],
},
)
result = response.json()<?php
$payload = json_encode([
"destination" => [
"mobile" => "+64272383189"
],
"message" => [
"type" => "text",
"text" => [
"body" => "Test"
]
],
"delivery_attempts" => [
[
"channel" => "wab",
"event" => "received",
"timeout" => 10
],
[
"channel" => "sms"
]
]
]);
$ch = curl_init("https://api.modicagroup.com/rest/im/v1/message");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Basic <TOKEN>",
"Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
require "json"
require "net/http"
require "uri"
uri = URI("https://api.modicagroup.com/rest/im/v1/message")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Basic <TOKEN>"
request["Content-Type"] = "application/json"
request.body = {
destination: {
mobile: "+64272383189"
},
message: {
type: "text",
text: {
body: "Test"
}
},
delivery_attempts: [
{
channel: "wab",
event: "received",
timeout: 10
},
{
channel: "sms"
}
]
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
endimport java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
String payload = """
{
"destination": {
"mobile": "+64272383189"
},
"message": {
"type": "text",
"text": {
"body": "Test"
}
},
"delivery_attempts": [
{
"channel": "wab",
"event": "received",
"timeout": 10
},
{
"channel": "sms"
}
]
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.modicagroup.com/rest/im/v1/message"))
.header("Authorization", "Basic <TOKEN>")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());using System.Text;
using var client = new HttpClient();
var request = new HttpRequestMessage(
HttpMethod.Post,
"https://api.modicagroup.com/rest/im/v1/message");
request.Headers.TryAddWithoutValidation("Authorization", "Basic <TOKEN>");
request.Content = new StringContent(
"""{"destination":{"mobile":"+64272383189"},"message":{"type":"text","text":{"body":"Test"}},"delivery_attempts":[{"channel":"wab","event":"received","timeout":10},{"channel":"sms"}]}""",
Encoding.UTF8,
"application/json");
var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();Note: the received event means the message was received by the recipient.
Send an IM message with a pre-defined template
curl -X POST 'https://api.modicagroup.com/rest/im/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <TOKEN>' \
-H 'X-Correlation-Id: f55c5554-87ed-4bde-8991-a2f4a1aa89fb' \
-d '{
"destination": {
"mobile": "+64272383189"
},
"message": {
"type": "template",
"template": {
"template_id": "bdff32db-1fd8-4270-99af-1f00c8ffdb3c",
"language": "es",
"parameters": [
{
"name": "reference",
"text": "AZXSNIJN"
}
]
}
},
"delivery_attempts": [
{
"channel": "wab",
"event": "read",
"timeout": 10
},
{
"channel": "sms"
}
]
}'
const response = await fetch("https://api.modicagroup.com/rest/im/v1/message", {
method: "POST",
headers: {
"Authorization": "Basic <TOKEN>",
"Content-Type": "application/json",
"X-Correlation-Id": "f55c5554-87ed-4bde-8991-a2f4a1aa89fb"
},
body: JSON.stringify({
destination: {
mobile: "+64272383189"
},
message: {
type: "template",
template: {
template_id: "bdff32db-1fd8-4270-99af-1f00c8ffdb3c",
language: "es",
parameters: [
{
name: "reference",
text: "AZXSNIJN"
}
]
}
},
delivery_attempts: [
{
channel: "wab",
event: "read",
timeout: 10
},
{
channel: "sms"
}
]
})
});
const result = await response.json();import requests
response = requests.post(
"https://api.modicagroup.com/rest/im/v1/message",
headers={
"Authorization": "Basic <TOKEN>",
"Content-Type": "application/json",
"X-Correlation-Id": "f55c5554-87ed-4bde-8991-a2f4a1aa89fb",
},
json={
"destination": {
"mobile": "+64272383189",
},
"message": {
"type": "template",
"template": {
"template_id": "bdff32db-1fd8-4270-99af-1f00c8ffdb3c",
"language": "es",
"parameters": [
{
"name": "reference",
"text": "AZXSNIJN",
},
],
},
},
"delivery_attempts": [
{
"channel": "wab",
"event": "read",
"timeout": 10,
},
{
"channel": "sms",
},
],
},
)
result = response.json()<?php
$payload = json_encode([
"destination" => [
"mobile" => "+64272383189"
],
"message" => [
"type" => "template",
"template" => [
"template_id" => "bdff32db-1fd8-4270-99af-1f00c8ffdb3c",
"language" => "es",
"parameters" => [
[
"name" => "reference",
"text" => "AZXSNIJN"
]
]
]
],
"delivery_attempts" => [
[
"channel" => "wab",
"event" => "read",
"timeout" => 10
],
[
"channel" => "sms"
]
]
]);
$ch = curl_init("https://api.modicagroup.com/rest/im/v1/message");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Basic <TOKEN>",
"Content-Type: application/json",
"X-Correlation-Id: f55c5554-87ed-4bde-8991-a2f4a1aa89fb"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
require "json"
require "net/http"
require "uri"
uri = URI("https://api.modicagroup.com/rest/im/v1/message")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Basic <TOKEN>"
request["Content-Type"] = "application/json"
request["X-Correlation-Id"] = "f55c5554-87ed-4bde-8991-a2f4a1aa89fb"
request.body = {
destination: {
mobile: "+64272383189"
},
message: {
type: "template",
template: {
template_id: "bdff32db-1fd8-4270-99af-1f00c8ffdb3c",
language: "es",
parameters: [
{
name: "reference",
text: "AZXSNIJN"
}
]
}
},
delivery_attempts: [
{
channel: "wab",
event: "read",
timeout: 10
},
{
channel: "sms"
}
]
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
endimport java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
String payload = """
{
"destination": {
"mobile": "+64272383189"
},
"message": {
"type": "template",
"template": {
"template_id": "bdff32db-1fd8-4270-99af-1f00c8ffdb3c",
"language": "es",
"parameters": [
{
"name": "reference",
"text": "AZXSNIJN"
}
]
}
},
"delivery_attempts": [
{
"channel": "wab",
"event": "read",
"timeout": 10
},
{
"channel": "sms"
}
]
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.modicagroup.com/rest/im/v1/message"))
.header("Authorization", "Basic <TOKEN>")
.header("Content-Type", "application/json")
.header("X-Correlation-Id", "f55c5554-87ed-4bde-8991-a2f4a1aa89fb")
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());using System.Text;
using var client = new HttpClient();
var request = new HttpRequestMessage(
HttpMethod.Post,
"https://api.modicagroup.com/rest/im/v1/message");
request.Headers.TryAddWithoutValidation("Authorization", "Basic <TOKEN>");
request.Headers.Add("X-Correlation-Id", "f55c5554-87ed-4bde-8991-a2f4a1aa89fb");
request.Content = new StringContent(
"""{"destination":{"mobile":"+64272383189"},"message":{"type":"template","template":{"template_id":"bdff32db-1fd8-4270-99af-1f00c8ffdb3c","language":"es","parameters":[{"name":"reference","text":"AZXSNIJN"}]}},"delivery_attempts":[{"channel":"wab","event":"read","timeout":10},{"channel":"sms"}]}""",
Encoding.UTF8,
"application/json");
var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();Note: the template bdff32db-1fd8-4270-99af-1f00c8ffdb3c accepts one parameter named reference which, in this message, will be replaced with the value: AZXSNIJN.
Send across WhatsApp, SMS and email
This example tries WhatsApp Business first, then SMS, then email. It gives the email a subject and adds your own reference. It also sets an expiry time, after which no further attempts are made.
curl -X POST 'https://api.modicagroup.com/rest/im/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <TOKEN>' \
-d '{
"destination": {
"mobile": "+64272383189",
"email": "jane.citizen@example.com"
},
"message": {
"type": "text",
"text": {
"subject": "Your order has shipped",
"body": "Your order 10452 has shipped and will arrive on Friday."
}
},
"delivery_attempts": [
{ "channel": "wab", "event": "read", "timeout": 3600 },
{ "channel": "sms", "event": "received", "timeout": 3600 },
{ "channel": "email" }
],
"reference": "order-10452",
"expires": "2026-11-05T10:00:00+13:00"
}'
const response = await fetch("https://api.modicagroup.com/rest/im/v1/message", {
method: "POST",
headers: {
"Authorization": "Basic <TOKEN>",
"Content-Type": "application/json"
},
body: JSON.stringify({
destination: {
mobile: "+64272383189",
email: "jane.citizen@example.com"
},
message: {
type: "text",
text: {
subject: "Your order has shipped",
body: "Your order 10452 has shipped and will arrive on Friday."
}
},
delivery_attempts: [
{ channel: "wab", event: "read", timeout: 3600 },
{ channel: "sms", event: "received", timeout: 3600 },
{ channel: "email" }
],
reference: "order-10452",
expires: "2026-11-05T10:00:00+13:00"
})
});
const result = await response.json();import requests
response = requests.post(
"https://api.modicagroup.com/rest/im/v1/message",
headers={
"Authorization": "Basic <TOKEN>",
"Content-Type": "application/json",
},
json={
"destination": {
"mobile": "+64272383189",
"email": "jane.citizen@example.com",
},
"message": {
"type": "text",
"text": {
"subject": "Your order has shipped",
"body": "Your order 10452 has shipped and will arrive on Friday.",
},
},
"delivery_attempts": [
{"channel": "wab", "event": "read", "timeout": 3600},
{"channel": "sms", "event": "received", "timeout": 3600},
{"channel": "email"},
],
"reference": "order-10452",
"expires": "2026-11-05T10:00:00+13:00",
},
)
result = response.json()<?php
$payload = json_encode([
"destination" => [
"mobile" => "+64272383189",
"email" => "jane.citizen@example.com"
],
"message" => [
"type" => "text",
"text" => [
"subject" => "Your order has shipped",
"body" => "Your order 10452 has shipped and will arrive on Friday."
]
],
"delivery_attempts" => [
["channel" => "wab", "event" => "read", "timeout" => 3600],
["channel" => "sms", "event" => "received", "timeout" => 3600],
["channel" => "email"]
],
"reference" => "order-10452",
"expires" => "2026-11-05T10:00:00+13:00"
]);
$ch = curl_init("https://api.modicagroup.com/rest/im/v1/message");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Basic <TOKEN>",
"Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
require "json"
require "net/http"
require "uri"
uri = URI("https://api.modicagroup.com/rest/im/v1/message")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Basic <TOKEN>"
request["Content-Type"] = "application/json"
request.body = {
destination: {
mobile: "+64272383189",
email: "jane.citizen@example.com"
},
message: {
type: "text",
text: {
subject: "Your order has shipped",
body: "Your order 10452 has shipped and will arrive on Friday."
}
},
delivery_attempts: [
{ channel: "wab", event: "read", timeout: 3600 },
{ channel: "sms", event: "received", timeout: 3600 },
{ channel: "email" }
],
reference: "order-10452",
expires: "2026-11-05T10:00:00+13:00"
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
endimport java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
String payload = """
{
"destination": {
"mobile": "+64272383189",
"email": "jane.citizen@example.com"
},
"message": {
"type": "text",
"text": {
"subject": "Your order has shipped",
"body": "Your order 10452 has shipped and will arrive on Friday."
}
},
"delivery_attempts": [
{ "channel": "wab", "event": "read", "timeout": 3600 },
{ "channel": "sms", "event": "received", "timeout": 3600 },
{ "channel": "email" }
],
"reference": "order-10452",
"expires": "2026-11-05T10:00:00+13:00"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.modicagroup.com/rest/im/v1/message"))
.header("Authorization", "Basic <TOKEN>")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());using System.Text;
using var client = new HttpClient();
var request = new HttpRequestMessage(
HttpMethod.Post,
"https://api.modicagroup.com/rest/im/v1/message");
request.Headers.TryAddWithoutValidation("Authorization", "Basic <TOKEN>");
request.Content = new StringContent(
"""{"destination":{"mobile":"+64272383189","email":"jane.citizen@example.com"},"message":{"type":"text","text":{"subject":"Your order has shipped","body":"Your order 10452 has shipped and will arrive on Friday."}},"delivery_attempts":[{"channel":"wab","event":"read","timeout":3600},{"channel":"sms","event":"received","timeout":3600},{"channel":"email"}],"reference":"order-10452","expires":"2026-11-05T10:00:00+13:00"}""",
Encoding.UTF8,
"application/json");
var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();Note: an email attempt needs destination.email, and a WhatsApp, SMS, MMS or RCS attempt needs destination.mobile. Each attempt is sent from the default sender configured for your application on that channel.
Request Reference
Request fields
| Field | Required | Description |
|---|---|---|
destination |
Yes | Who to send to. Set mobile (E.164 format, such as +64272383189), email, or both, to cover every channel you use. |
message |
Yes | The message content. type is text or template, with a matching text or template object. |
delivery_attempts |
No | The channels to try, in order. From 1 to 10 attempts. If omitted, the message is sent by SMS. |
reference |
No | Your own reference for the message, up to 255 characters. It is returned in status callbacks. |
mask |
No | A sender mask to apply to the message, up to 20 characters. |
expires |
No | An RFC 3339 date and time, such as 2026-11-05T10:00:00+13:00. The message is not delivered after this time. |
charset |
No | The character set for email content: ASCII, UTF-8, ISO-8859-1 or Shift_JIS. |
Text messages
| Field | Required | Description |
|---|---|---|
text.body |
Yes | The message content, up to 10,000 characters. |
text.subject |
No | The email subject, up to 256 characters. Used by email attempts only. It may contain letters, numbers, spaces, hyphens and underscores. |
Template messages
| Field | Required | Description |
|---|---|---|
template.template_id |
Yes | The ID of a pre-defined template. |
template.language |
No | The template language code, such as en or es. |
template.parameters |
No | Up to 20 name and text pairs. Each text replaces the named parameter in the template, up to 256 characters. |
Delivery attempts
Each delivery attempt has these fields:
| Field | Required | Description |
|---|---|---|
channel |
Yes | One of wab (WhatsApp Business), sms, mms, email or rcs. |
event |
All attempts except the last | The status that counts as success for this attempt, such as received or read. |
timeout |
All attempts except the last | How long to wait for event, in seconds, before moving to the next attempt. From 0 to 604800 (7 days). |
The attempts run in order. If an attempt reaches its event within its timeout, delivery stops there. Otherwise the next attempt starts. The last attempt has no fallback, so it needs no event or timeout.
Errors
| Status | Meaning |
|---|---|
202 |
The message was accepted. The response body contains its id. |
400 |
The request body is not valid JSON or does not match the API schema. |
401 |
The credentials are missing or wrong, or the request came from an IP address that is not authorised. |
422 |
The request is well formed but failed validation. The response lists each problem. |
429 |
Too many requests. Slow down and retry. |
500 |
An internal error occurred. Retry later. |
422 response:
{
"message": "Validation failed",
"errors": [
{
"field": "delivery_attempts.0.timeout",
"description": "timeout must not be empty"
},
{
"field": "destination.email",
"description": "email must not be empty"
}
]
}
Status Callbacks
You will only receive status callbacks if you have configured a status callback URL for your IM API application. We recommend using https:// for your callback URL.
When the status of a message changes, a POST request is made to your callback URL with a JSON body:
{
"id": "b95fc11e-37f0-4770-a082-6ea22d4c4d12",
"status": "received",
"channel": "sms",
"reference": "order-10452"
}
| Field | Description |
|---|---|
id |
The message ID returned when the message was accepted. |
status |
The new status. See Message status. |
channel |
The delivery attempt’s channel, such as wab, sms or email. Omitted when the status is about the message as a whole, for example when it is rejected before any attempt is made. |
detail |
More information about the status, when available. |
reference |
The reference you sent with the message. Present only if you set one. |
You can receive several callbacks for one message: one for each status change of each delivery attempt, and one for the message as a whole. Use channel to tell which attempt a callback is about.
Message status
| Status | Description |
|---|---|
| accepted | The message has been accepted for delivery |
| submitted | The message has been submitted to the channel for delivery |
| sent | The message has been sent by the channel |
| received | The message has been received by the recipient |
| read | The recipient has read the message |
| frozen | A transient error has frozen this message |
| rejected | The message was rejected. detail describes the reason |
| failed | Message delivery has failed |
| dead | Message killed by an administrator |
| expired | The message could not be delivered before it expired |
Help
Having trouble integrating with any of our services? Contact support@modicagroup.com and we’ll help you sort it out.