Send SMS (Batch)

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 support@mainbrainer.com 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.

Copy
Copied

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

Copy
Copied
    "status": "Success",
    "message": "Successfully accepted.",
    "data": {
        "QueueId": "36032bdc-1716-4205-9c10-69a61c17909e",
        "QueuedTimestamp": 1631601011202
    }
}

Sample Code snippets

NodejsJavascriptC#PHPjavaGoPython
Copy
Copied
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);
;
Copy
Copied
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);
Copy
Copied
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);
    }
  }
}
Copy
Copied
/**
 * 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;
}
Copy
Copied
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());
  }
}
Copy
Copied
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))
}
Copy
Copied
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)