Send Bulk messaging campaigns

Delivering large quantities of SMS messages to mobile phones is widely called bulk SMS or mass SMS. Bulk messaging is used by Media Companies, Banks or consumer brands for marketing and/or entertainment.
Delivering the same message to many recipients is one of the most common tasks an application might facilitate. This functionality could also be used for reminders - in case of an event - or alerts.

As an example, your application might use bulk messaging to inform about an event planned, at a specific place or time. Commercial communication might also include Sales, Discounts, Coupons, New offers, Wishes etc.

1. Bulk SMS advantages

  • SMS message delivery is fast and reliable. Almost instant.
  • Delivered to a mobile phone, messages are opened and read by more than 98% of the recipients, an average of 5 seconds after message delivery.
  • You know the exact time your message is delivered, as opposed to other communication channels.
  • An SMS needs no extra setup or software to be read. People keep their mobile device handy most of the time.
  • Bulk messaging is cheap; compared to other forms of communication, a cost of 30$ for 1000 SMS is low.
  • Consider the environment. Green communication - condensed text delivered fast, using less energy than any other means.

2. Routee's advanced bulk SMS API

Routee API provides some of the most advanced features.

By using the Routee API bulk messaging, you put your messaging load on Routee and stay focused on your application's functionality. You can customise your message by using Routee's advanced Contacts API.

Send your messages to multiple recipients and use parameters to personalize the message content.

You are respecting your customers' privacy and follow local country legal restrictions by using Routee's "Quiet Hours" features.

Use advanced Message tracking. Make sure your message has been delivered on time and schedule your next campaign.

Group your bulk messages as "Campaigns" and use Routee's Console to view reports, graphs and calculate the cost.

Written in any language, your message will be delivered and read by your recipients even if you need to send large texts (more than 160 characters)!

Your set of bulk messages is then queued until it is scheduled to go!

3. Setting custom parameters for your recipients

We can add any contact label as well as any user defined labels to a text message.

A label is a property -you may call it a custom field- defined in Routee platform, to store extra information for a contact.

If a contact doesn’t have the a property set, it will be replaced with an empty string.
Instead of an empty string, we can use a fallbackValue by setting the following property:

This will replace the [~firstName] with "dude" if a contact doesn’t have a firstName set.

"fallbackValues": {
    "firstName": "dude"

4. Send bulk SMS from your application

In this guide we will delve into how you can send a personalized message from your web application (let’s call it MindPuzzle) to all your customers, informing them that a new version is available.

We assume you have imported your contacts into Routee platform and grouped them under a group called "customers".

Check how you can Authenticate to get an access_token and send your first SMS! Read more ...

Your application should use the following URL for the Routee API call.



AuthorizationBearer {access_token}

By entering [~firstName] we set Routee to replace that string with the contacts' firstName property.


curl --request POST \
  --url \
  --header 'authorization: Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4' \
  --header 'content-type: application/json' \
  --data '{"body": "Hello [~firstName] a new version of MindPuzzle is available. Check it out", "groups" : [ "customers" ],"from": "mindpuzzle"}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"body\": \"Hello [~firstName] a new version of MindPuzzle is available. Check it out\", \"groups\" : [ \"customers\" ],\"from\": \"mindpuzzle\"}");

Request request = new Request.Builder()
  .addHeader("authorization", "Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4")
  .addHeader("content-type", "application/json")

Response response = client.newCall(request).execute();
var client = new RestClient("");
var request = new RestRequest(Method.POST);

request.AddHeader("content-type", "application/json");
request.AddHeader("authorization", "Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4");
request.AddParameter("application/json", "{\"body\": \"Hello [~firstName] a new version of MindPuzzle is available. Check it out\", \"groups\" : [ \"customers\" ],\"from\": \"mindpuzzle\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "",
  CURLOPT_POSTFIELDS => "{\"body\": \"Hello [~firstName] a new version of MindPuzzle is available. Check it out\", \"groups\" : [ \"customers\" ],\"from\": \"mindpuzzle\"}",
    "authorization: Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4",
    "content-type: application/json"

$response = curl_exec($curl);
$err = curl_error($curl);


if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
import http.client

conn = http.client.HTTPSConnection("")

payload = "{\"body\": \"Hello [~firstName] a new version of MindPuzzle is available. Check it out\", \"groups\" : [ \"customers\" ],\"from\": \"mindpuzzle\"}"

headers = {
    'authorization': "Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4",
    'content-type': "application/json"

conn.request("POST", "/sms/campaign", payload, headers)

res = conn.getresponse()
data =

require 'uri'
require 'net/http'

url = URI("")

http =, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request =
request["authorization"] = 'Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4'
request["content-type"] = 'application/json'
request.body = "{\"body\": \"Hello [~firstName] a new version of MindPuzzle is available. Check it out\", \"groups\" : [ \"customers\" ],\"from\": \"mindpuzzle\"}"

response = http.request(request)
puts response.read_body
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "",
  "method": "POST",
  "headers": {
    "authorization": "Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4",
    "content-type": "application/json"
  "processData": false,
  "data": "{\"body\": \"Hello [~firstName] a new version of MindPuzzle is available. Check it out\", \"groups\" : [ \"customers\" ],\"from\": \"mindpuzzle\"}"

$.ajax(settings).done(function (response) {
#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"authorization": @"Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4",
                           @"content-type": @"application/json" };
NSDictionary *parameters = @{ @"body": @"Hello [~firstName] a new version of MindPuzzle is available. Check it out",
                              @"groups": @[ @"customers" ],
                              @"from": @"mindpuzzle" };

NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@""]
[request setHTTPMethod:@"POST"];
[request setAllHTTPHeaderFields:headers];
[request setHTTPBody:postData];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
[dataTask resume];

Message with the senderID mindpuzzle is sent to all your customers!
George Martin will get a message saying:

"Hello George a new version of MindPuzzle is available. Check it out"

To get more information for sending bulk SMS check out our Resource Reference


Validation Error!

If the HTTP response has 400 status code, with "code":"400005000", then your SMS campaign contains invalid data, specified in "errors" array.

008 errorCode indicates that some recipients are invalid (either a mobile number in "to" array, a contact, or inside a group).
In order to send your campaign, try to exclude these invalid recipients (remove them from the selected group, "to" or "contacts" array) and send again the HTTP request.
You can find the invalid numbers as "property" in "errors" array, with "errorCode":008.