Textlocal Logo

API Documentation

Send SMS via Bulk JSON API

We also offer a bulk JSON interface for sending different messages to multiple recipients in bulk. This option is perfect for mail-merging text. We recommend no more than 500 tags in each submission.

Resource URL

https://api.txtlocal.com/bulk_json

Sample Request

<?php

$messages = array(
    // Put parameters here such as sender, force or test
    'sender' => "SampleName",
    'messages' => array(
        array(
            'number' => 447123456789,
            'text' => rawurlencode('This is your message')
        ),
        array(
            'number' => 447987654321,
            'text' => rawurlencode('This is another message')
        )
    )
);

// Prepare data for POST request
$data = array(
    'apikey' => 'Your API key',
    'data' => json_encode($messages)
);

// Send the POST request with cURL
$ch = curl_init('https://api.txtlocal.com/bulk_json/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

echo $response;
<?php

$textlocal = new Textlocal(false, false, 'Your apiKey');

$data = array(
    'messages' => array(
        array(
            'number' => 447123456789,
            'text' => 'This is your message'
        ),
        array(
            'number' => 447987654321,
            'text' => 'This is another message'
        )
    )
);

$data = json_encode($data);
$response = $textlocal->sendBulkSms($data);

echo json_encode($response);

Caution: Some users opt to place their request inside a code loop, while testing we highly recommend setting the test parameter to true, as occasionally an infinite loop can occur and users can consume all their credits very quickly.

Parameters

data The JSON payload. The only required parameter is “messages”, an array that must include both a “number” and “text” parameter for the message. Optionally it can include a “unicode” parameter if you wish to send the message in unicode, providing your account has unicode enabled.
Login Parameters (Additional Information)
apiKey You can create these in your Messenger Control Panel (click here) for each application, and limit the usage of them by host IP Address.
Data Parameters—Optional parameters that can be included in the JSON data payload
sender Use this field to specify the sender name for your message. This must be at least 3 characters in length but no longer than 11 alphanumeric characters or 13 numeric characters.
scheduled This parameter can be used to specify a scheduled date/time for your message, which should be provided in Unix timestamp format. Times should be provided in GMT.
receiptUrl Use this field to specify an alternative URL to which the delivery receipt(s) will be sent. See handling receipts documentation.
force If included and set to false, this will not send any messages if 1 or more messages in the send fails for any reason. If not provided defaults to true.
optouts If included and set to false, this will prevent opt-outs being honoured on your account. If not provided defaults to true.
test Set this field to true to enable test mode, no messages will be sent and your credit balance will be unaffected. If not provided defaults to false.

Sample Response

{
    "messages":[
        {
            "balance":1161,
            "batch_id":123456789,
            "cost":1,
            "num_messages":1,
            "message":{
                "num_parts":1,
                "sender":"Jims Autos",
                "content":"This is your message"
            },
            "receipt_url":"",
            "custom":"",
            "messages":[
                {
                    "id":1151347780,
                    "recipient":447123456789
                }
            ]
        },
        {
            "balance":1160,
            "batch_id":123456790,
            "cost":1,
            "num_messages":1,
            "message":{
                "num_parts":1,
                "sender":"Luigis",
                "content":"This is your message"
            },
            "receipt_url":"",
            "custom":"",
            "messages":[
                {
                    "id":1,
                    "recipient":447987654321
                }
            ]
        }
    ],
    "balance_pre_send":1162,
    "total_cost":2,
    "balance_post_send":1160,
    "status":"success"
}

Errors

Error Codes
4 No recipients specified.
5 No message content.
6 Message too long.
7 Insufficient credits.
8 Invalid schedule date.
9 Schedule date is in the past.
10 Invalid group ID.
11 Selected group is empty.
15 Invalid JSON string.
32 Invalid number format.
33 You have supplied too many numbers.
34 You have supplied both a group ID and a set of numbers.
43 Invalid sender name.
44 No sender name specified.
51 No valid numbers specified.
57 No messages found.
80 Invalid Template. The message given didn't match any approved templates on your account.
204 Invalid message content.
314 One or more messages failed to send. No messages sent.

Warnings

Warning Codes
3 Invalid number.