# 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](https://wiki.mobivatebulksms.com/archived-docs/send-single-sms-message).

<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 %}