Send Bulk SMS
POST /SMS/Batch/
This endpoint is used to send an SMS to multiple recipients in one go. The SMSs can be sent immediately or scheduled for delivery at a later date and time.
Usage scenario for this endpoint:
This endpoint is especially useful for sending out marketing campaigns like promotions for upcoming sales, special discount coupons, or event promotions, etc., to your contact lists.
Method | Details |
---|---|
HTTP Method | POST |
Content type | Application/json |
Requires authentication? | YES |
Rate limited? | YES |
Headers | User-Agent |
Module | SMS |
End Point
https://apisms.mainbrainer.com/sms/batch
Required Parameters | Usage | Description |
---|---|---|
Access Token or API Key | Authorization: Bearer {token} header | Pass the API key in the request header for request authentication. Read more about our authentication process. |
Sender Name | Used in the request body | In case you wish to use a custom sender name for your SMS sending, write to us at [email protected] to create and verify a custom sender name. If you don’t wish to create a custom sender name, you can use MainBrainer as the sender name for your SMS sendings. |
Body | Used in the request body | This parameter includes the complete text of the SMS you wish to send. |
Recipient | Used in the request body | This parameter specifies the mobile numbers to which you want to send an SMS. Also, ensure that you prefix the country code to the mobile number. For example, when sending messages to a mobile number in Norway, the to parameter value should look like – 4793454496 , where 47 is the country code for Norway, and 93454496 is the intended recipient mobile number. |
ListID | listId (uuid) eg: "3fa85f64-5717-4562-b3fc-2c963f66afa6 | Each contact list in the MainBrainer CRM is assigned a unique List ID that acts as a Unique identifier for the particular list. In case you wish to send the SMS to contacts of a particular list, specify the list ID of the desired list using the parameter listId . |
Note
In case the message body is more than 160 GSM-7 characters long (or more than unicode 70 UCS-2 characters), your messages will be split into multiple 160-character messages and concatenated, resulting in separately billed messages.Read more about SMS encoding on MainBrainer.
Note
To identify the recipients for the SMS sending, it is mandatory to specify at least one of the parameters - List ID or the parameter - recipients. In case you wish to include manually added recipients in addition to contacts of a MainBrainer CRM list, pass the relevant values in both the parameters - List ID and recipients.
Note
MainBrainer supports Alphanumeric Sender IDs
for use as Sender Names. Kindly ensure that you use a sender name compliant with the rules and regulations of the country where you wish to send the SMSs.
Note
The scheduled date and time of the message should be specified in the RFC3339 format (Y-m-d\TH:i:sP).
Optional Parameters | Usage | Description |
---|---|---|
Body Encrypted | Isbodyencrypted = boolean and default = false | Pass the parameter value as Isbodyencrypted if you wish to encrypt your message body. Doing so helps you encrypt important information like password and other Secure details that might be a part of the message body. |
Personalization Substitution Tags | tagName = string, tagValue = string | These tags help you insert dynamic data at the time of SMS sending. In order to substitute the data at the time of the sending, follow the pattern "substitution_tag":"value” to substitute for the key/value pairs. -- In case you use the parameter recipients to identify the SMS recipients, the substitutions will work as specified. -- In case you use the parameter listID to identify the recipients, the data will get substituted on the basis of the information stored in the MainBrainer CRM for the recipient mobile number. -- In case you use both the parameters listID and recipients to identify the SMS recipients, and the information passed under recipients is not in conformity with the information stored in the CRM list, data will get substituted on the basis of information passed under the parameter recipients. -- In case you use the parameter ListID to identify multiple Lists, and a contact exists in both the lists with different information, data will get substituted with information from the most recently updated contact. |
Scheduled Date-time | RFC3339 format (Y-m-d\TH:i:sP) | Pass the scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP). The date and time passed in this parameter will be converted as per the offset value specified in your account settings. |
Landing Page ID | landingpageid (uuid) eg: "3fa85f64-5717-4562-b3fc-2c963f66afa6 | Landingpageid is the unique identifier for a landing page created in your MainBrainer account. In case you wish to include a landing page in your SMS Sending, pass the landing page ID as the parameter value. |
Unique URL | Isuniqueurl = boolean and default = true | In case you wish to monitor recipient-specific analytics for the SMS sending, send the landing page as a unique URL. |
Shortner URL | shortnerUrl = string, default = sms.club | In case you wish to use a custom shortener for your landing page, specify the same here. Otherwise, we’ll use the default shortener sms.club |
Webhook URL | Delivery Status | Use this parameter to specify the webhook URL where you want to receive delivery status updates for the SMS being sent. When the SMS operator returns a delivery status, the status is instantly posted to this webhook URL. Using a Webhook enables your application to receive delivery updates as they happen, in an easily parsable JSON format. Updates will be sent for the following delivery statuses:+ Submitted+ Processed+ Delivered+ Failed |
Landing Page and Landing page ID
Every Landing Page on MainBrainer is assigned a Landing Page ID that acts as a unique identifier for the landing page. To read more about creating landing pages on MainBrainer, refer to our detailed article series.
Response
In case there is a problem with the data in the request body, or if there are no properties included in the request, we'll return a 400 and 422 response along with additional details listing the cause.
This example demonstrates how to send a batch of SMSs to manually added recipients
along with a list’s contacts.
post url: https://apisms.loyaltycommunication.com/sms/batch
{
"listId": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"recipients": [
{
"mobileNo": 4790812501,
"personalizationSubstitutionTags": [
{
"tagName": "[firstname]",
"tagValue": "Tom"
}
]
}
],
"senderName": "MainBrainer",
"isBodyEncrypted": false,
"body": "Hi [firstname], test SMS from MainBrainer.",
"scheduleDateTime": "2021-03-11T11:43:55.759Z",
"landingPageId": "00000000-0000-0000-0000-000000000000",
"shortner": {
"shortnerUrl": "sms.club",
"isUniqueUrl": true
},
"webHookUrl": "https://webhook-url.yourdomain.com"
}
Returns a 202 Accepted response with content on success.
Response Body
"status": "Success",
"message": "Successfully accepted.",
"data": {
"QueueId": "36032bdc-1716-4205-9c10-69a61c17909e",
"QueuedTimestamp": 1631601011202
}
}
Sample Code snippets
const fetch = require('node-fetch');
const resp = await fetch(
`https://apisms.mainbrainer.com/sms/batch`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json-patch+json',
Authorization: 'YOUR_API_KEY_HERE'
},
body: `[object Object]`
}
);
const data = await resp.text();
console.log(data);
;
const resp = await fetch(
`https://apisms.mainbrainer.com/sms/batch`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json-patch+json',
Authorization: 'YOUR_API_KEY_HERE'
},
body: `[object Object]`
}
);
const data = await resp.text();
console.log(data);
using System;
using System.Net.Http;
using System.Threading.Tasks;
public class Program
{
public static async Task Main(string[] args)
{
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Add("Authorization", "YOUR_API_KEY_HERE");
var request = await client.PostAsync("https://apisms.mainbrainer.com/sms/batch", postData);
var response = await request.Content.ReadAsStringAsync();
Console.WriteLine(response);
}
}
}
/**
* Requires libcurl
*/
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_HTTPHEADER => [
"Authorization: YOUR_API_KEY_HERE",
"Content-Type: application/json-patch+json"
],
CURLOPT_POSTFIELDS => "[object Object]",
CURLOPT_URL => "https://apisms.mainbrainer.com/sms/batch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$error = curl_error($curl);
curl_close($curl);
if ($error) {
echo "cURL Error #:" . $error;
} else {
echo $response;
}
import java.net.*;
import java.net.http.*;
import java.util.*;
public class App {
public static void main(String[] args) throws Exception {
var httpClient = HttpClient.newBuilder().build();
var host = "https://apisms.mainbrainer.com";
var pathname = "/sms/batch";
var request = HttpRequest.newBuilder()
.POST(HttpRequest.BodyPublishers.ofString(payload))
.uri(URI.create(host + pathname ))
.header("Content-Type", "application/json-patch+json")
.header("Authorization", "YOUR_API_KEY_HERE")
.build();
var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
reqUrl := "https://apisms.mainbrainer.com/sms/batch"
payload := strings.NewReader("[object Object]")
req, _ := http.NewRequest("POST", reqUrl, payload)
req.Header.Add("Content-Type", "application/json-patch+json")
req.Header.Add("Authorization", "YOUR_API_KEY_HERE")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
import requests
url = "https://apisms.mainbrainer.com/sms/batch"
payload = '''
[object Object]
'''
headers = {
"Content-Type": "application/json-patch+json",
"Authorization": "YOUR_API_KEY_HERE"
}
response = requests.post(url, data=payload, headers=headers)
data = response.json()
print(data)