# 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

### <mark style="color:green;">`POST`</mark> `/send/batch`&#x20;

#### 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

```bash
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.

{% hint style="info" %}
All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request.
{% endhint %}

#### 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.

```json
{
  "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.

```json
{
  "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.