> For the complete documentation index, see [llms.txt](https://wiki.mobivatebulksms.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.mobivatebulksms.com/archived-docs/send-batch-sms-messages.md).

# Send Batch SMS Messages

This document will describe how to send batch SMS messages.

Batch messages allows you to send up to 1,000 messages per Batch SMS request. These are useful for large campaigns. 

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

Send batch SMS messages to a number of receipients.&#x20;

{% tabs %}
{% tab title="Curl" %}

```json
curl -X POST "https://api.mobivatebulksms.com/send/batch" \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [API KEY]' \
-d '{
  "routeId": "mglobal",
  "scheduleDateTime": "2024-08-01T10:00:00+0200",
  "excludeOptouts": false,
  "excludeDuplicates": false,
  "spreadHours": 0,
  "recipients": [
    {
      "reference": "ref-001",
      "text": "This is a test message with full options",
      "routeId": "mglobal",
      "originator": "Brand",
      "recipient": "440000001"
    }
  ],
  "shortenUrls": false,
  "name": "August Campaign"
}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.mobivatebulksms.com/send/batch"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer [API KEY]"
}
payload = {
    "routeId": "mglobal",
    "scheduleDateTime": "2024-08-01T10:00:00+0200",
    "excludeOptouts": False,
    "excludeDuplicates": False,
    "spreadHours": 0,
    "recipients": [
        {
            "reference": "ref-001",
            "text": "This is a test message with full options",
            "routeId": "mglobal",
            "originator": "Brand",
            "recipient": "440000001"
        }
    ],
    "shortenUrls": False,
    "name": "August Campaign",
    "id": "campaign-001"
}

response = requests.post(url, json=payload, headers=headers)
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Please note,** to schedule a date time as a parameter, the date time parameter must be set to a time in the future.&#x20;
{% endhint %}

**Headers**

| Header        | Value             |
| ------------- | ----------------- |
| Content-Type  | application/json  |
| Authorization | Bearer \[Api-Key] |

**Body**

<table><thead><tr><th>Name</th><th width="109.21875">Type</th><th width="122.63671875">Required?</th><th>Description</th></tr></thead><tbody><tr><td>routeId</td><td>string</td><td>Yes</td><td>Route for messages.</td></tr><tr><td>name</td><td>string</td><td>No</td><td>Campaign name, used for reporting purposes.</td></tr><tr><td>shortenUrls</td><td>boolean</td><td>No</td><td>Default: <em><strong>false</strong></em> (URLs will not be shortened)<br>Set to <em>true</em> to shorten long URLs<br>Reduces message size and allows click tacking.</td></tr><tr><td>excludeOptouts</td><td>boolean</td><td>No</td><td>Default: <em><strong>true</strong></em> (Optouts are excluded)<br>Set to <em>false</em> to turn off Optout filtering.</td></tr><tr><td>excludeDuplicates</td><td>boolean</td><td>No</td><td>Default: <em><strong>true</strong></em> (Duplicates are excluded)<br>Set to <em>false</em> if you wish to send multiple messages to the same recipient(s).</td></tr><tr><td>scheduleDateTime</td><td>datetime</td><td>No</td><td>Default: <em><strong>null</strong></em> (Campaign is sent immediately)<br>Specify a date/time to schedule delivery at a later date<br>Example: 2024-01-26T15:30:00+0530</td></tr><tr><td>spreadHours</td><td>integer</td><td>No</td><td>Default: <em><strong>0</strong></em> (Spread the campaign over X hours) Specify a number of hours to spread the campaign over.</td></tr><tr><td>recipients</td><td>list</td><td>Yes</td><td>List of recipients to send the batch of SMS messages to. See arguments below.</td></tr></tbody></table>

#### Arguments

Recipient arguments are largely the same as when sending a single SMS message, [see here](/archived-docs/send-single-sms-message.md).

<table><thead><tr><th>Name</th><th width="131">Type</th><th width="111">Required?</th><th>Description</th></tr></thead><tbody><tr><td>originator</td><td>string</td><td>Yes</td><td>Originator/SenderID for SMS messages (MaxLength - AlphaNumeric: 11, numeric: 15).</td></tr><tr><td>recipient</td><td>string</td><td>Yes</td><td>Recipient of SMS Message (Numeric only, MSISDN format inc international prefix).</td></tr><tr><td>text</td><td>string</td><td>Yes</td><td>Message text. </td></tr><tr><td>routeID</td><td>string</td><td>No</td><td>Specified message route. </td></tr><tr><td>reference</td><td>string</td><td>No</td><td>Your reference, will be provided as part of the delivery receipt for correlation. </td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "id": "4dbe11c6bda241e394889f2f3cc66cf8",
    "name": "August Campaign",
    "routeId": "mglobal",
    "shortenUrls": false,
    "spreadHours": 0,
    "excludeOptouts": false,
    "excludeDuplicates": false,
    "scheduleDateTime": "2024-08-01T08:00:00+0000",
    "recipients": [
        {
            "originator": "Brand",
            "recipient": "440000001",
            "text": "This is a test message with full options",
            "reference": "ref-001",
            "routeId": "mglobal"
        }
    ]
}
```

{% endtab %}

{% tab title="401" %}

```json
{
   "code":401,
   "message":"Unauthorized"
}
```

{% endtab %}
{% endtabs %}