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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.mobivatebulksms.com/archived-docs/send-batch-sms-messages.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.