Add Batch

Add a Batch to the queue to be sent

Supported features

• Multi channel support

Request

Endpoint

Messaging Plus expects a POST request

POST https://mplus.instagiv.com/batch

Query strings

Key	Required	Description	Example
key	true	Account API key	?key=aaaabbbbcccc111222333
isDryrun	false	Whether this batch should be processed in 'dryrun' mode. Dryrun messages are not added to the queue. Defaults to false	?dryRun=true
allowMulti	false	Whether multi-part messages are accepted	?allowMulti=true

Body

Simple

// Sending a single message
{
    "from": "mplus-test",
    "message": "mplus test message!",
    "destinations": [
        "441111111111"
    ]
}

All parameters

// Showing usage of all available parameters
{
    "from": "mplus-test",
    "message": "mplus test message!",
    "destinations": [
        "441111111111"
    ],
    "callback": "https://my-callback.com/delivery-receipt",
    "id": "b2693dfe-0813-427a-bc2f-62b0e9292403",
    "send_at": "2026-01-01T09:00:00Z",
    "channel": "rcs",
    "fallback_channels": ["sms"]
}

Multiple destinations

// Sending multiple messages
{
    "from": "mplus-test",
    "message": "mplus test message!",
    "destinations": [
        "441111111111", "442222222222", "443333333333",
        "444444444444", "445555555555"
    ]
}

This example shows the minimum required to send a message

Body parameters

Key	Required	Expected value	Description
from	true	string	Sender ID
message	true	string	Body content to send in batch
destinations	true	string[]	List of E.164 formatted mobile numbers to send to
callback	false	string	URL to send webhook/callback delivery receipts to
uuid	false	string	UUID string identifier for the batch (batch-uuid)
at	false	string	ISO 8601 formatted timestamp, representing when to send this batch. Expects a timestamp >5 minutes into the future. GMT timezone
channel	false	string	Initial channel to send via. Available channels
fallback_channels	false	string[]	Priority ordered list of message channels to try sending via. Available channels

Response

Body

{
    "identifier": "c4ae0c8a-bbb2-4ce3-8ebc-5d8df1751d8d"
}

Body parameters

Key	Expected value	Description
identifier	string	The batch uuid of your message(s)

Specify Callback Endpoint

To receive Delivery receipts via Webhook requests, you can specify an endpoint on your system that you want them to be sent to.

// Specify the callback endpoint in the message body
{
    "from": "mplus-test",
    "message": "mplus test message!",
    "destinations": [
        "441111111111"
    ],
    "callback": "https://my-website.com/delivery-receipt"
}

Specifying Channels

To specify the channel you want to send via, specify the channel parameter. To specify channels to fall back to in case of failure with the first, specify the fallback_channels parameter

---

POST https://mplus.instagiv.com/batch

{
    "from": "mplus-test",
    "message": "mplus test message!",
    "destinations": [
        "441111111111"
    ],
    "channel": "rcs",
    "fallback_channels": ["sms"]
}