Send Batch SMS Messages

Send SMS messages to multiple recipients in a single request. This is commonly referred to as sending a campaign.

Batch messages support:

• Multiple recipients

• Per-recipient metadata for message personalisation

• Optional per-recipient overrides (text and originator)

• Mailing list recipients

POST /send/batch

Required Permission

create:BatchSMS

Your API key must have this permission enabled in order to use this endpoint.

Message Personalisation

You can include meta fields for each recipient and reference them within your message using template tags.

For example:

Hello {{NAME}}, how is the weather in {{CITY}}?

Each recipient’s meta object determines how the message is rendered.

Example Request

curl --location 'https://<hostname>/send/batch' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "recipients": [
      {
        "recipient": "4479000000001",
        "reference": "aaa",
        "meta": {
          "NAME": "John",
          "CITY": "London"
        }
      },
      {
        "recipient": "4479000000002",
        "reference": "bbb",
        "meta": {
          "NAME": "Jack",
          "CITY": "Dublin"
        }
      },
      {
        "recipient": "4479000000003",
        "reference": "ccc",
        "originator": "CustomOrigin",
        "text": "Hello Michael. How are you?"
      },
      {
        "recipient": "3392287d-7a79-4789-9ef8-7dc174836688",
        "meta": {
          "type": "mailinglist"
        }
      }
    ],
    "text": "Hello {{NAME}}, how is the weather in {{CITY}}?",
    "originator": "test",
    "name": "My Campaign",
    "shortenUrls": true,
    "excludeDuplicates": true,
    "excludeOptOuts": true,
    "spreadHours": 0
  }'

Replace YOUR_API_KEY with your API key.

All endpoints shown in this documentation use a sample base URL. The production API endpoint is provided by our team upon request.

Request Parameters

Field	Type	Required	Description
text	string	Yes	The SMS message content.
originator	string	Yes	The sender ID displayed on the recipient’s handset.
recipient	string	Yes	The destination phone number in international format.
shortenUrls	boolean	No	Whether URLs in the message should be automatically shortened.
excludeOptouts	boolean	No	Whether opted-out recipients should be excluded from delivery.
spreadHours	number	No	Spread message delivery evenly over the specified number of hours.
scheduleDateTime	string (ISO 8601 datetime)	No	Schedules the message or campaign to be sent at a future date and time. The value must be provided in ISO 8601 format (e.g. 2025-03-01T14:30:00Z). If omitted, the message or campaign is sent immediately.

Responses

Authentication Error (HTTP 403)

Returned when the API key is invalid or does not have the required permission.

{
  "success": false,
  "error": {
    "name": "AuthenticationError",
    "statusCode": 403
  }
}

Validation Error (HTTP 400)

Returned if the API key is invalid or missing the required permission.

Success (HTTP 200)

Returned when the campaign has been successfully accepted for delivery.

{
  "success": true,
  "record": {
    "id": "8af60d9-de7f-45ce-97f1-35a91b45277",
    "type": "BatchSMS",
    "scheduled": "2025-11-10T21:12:32.786Z",
    "recipientCount": 5
  }
}

A successful response confirms that the campaign has been queued. Message delivery and delivery receipts are processed asynchronously.