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:

  1. Authenticate with your IM API credentials.
  2. Submit a message request to /message.
  3. Include the destination, message body or template, and optional delivery attempts.
  4. If delivery attempts are provided, the API tries each channel in order.
  5. 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:

  1. Your IM API application has been provisioned.
  2. You have the application name and password for HTTP Basic Authentication.
  3. Your sending server IP address is authorised if IP allowlisting is enabled.
  4. The recipient mobile number is in international format.
  5. Any WhatsApp templates used in template messages are already configured and approved.
  6. If you send by email, your sender email address has been set up for your application.
  7. 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:

  1. Authenticate using your IM API credentials.
  2. Submit a simple POST request to /message with a mobile destination and text body.
  3. Confirm the 202 response and store the returned message ID.
  4. Add delivery attempts after the simple SMS request succeeds.
  5. 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)
end
import 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)
end
import 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)
end
import 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)
end
import 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.

warningNOTE: The security certificate must match the domain name being used, self signed certificates will not verify and will generate errors.

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.