Batch SMS API

Through this API, you can send a batch of 1 to 5,000 global SMS messages in a single request. It is ideal for large-scale notifications, promotional campaigns, alerts, and automated message sending. PaaSoo has specifically optimized this API for high-volume sending scenarios and provides flexible parameter configuration options to meet various business needs.

Features and Use Cases

• Large-scale Notifications: Such as emergency alerts, event announcements, or system maintenance notices that need to reach a massive audience at once.
• Marketing Campaigns: Sending coupons, discount information, and holiday promotions in bulk to quickly expand promotional coverage.
• Platform Service Alerts: Including express logistics updates, membership renewal reminders, appointment confirmations, etc.
• Automated Tasks: Sending SMS to specific audience segments in bulk via scheduled or event-driven methods to improve efficiency.

With this API, you can bundle multiple numbers into one request, while still tracking and managing the delivery status and Message ID of each individual SMS. You can also use the batchid for subsequent queries, statistics, or reconciliation. If you need to check the delivery results or success rate of your batch SMS, please refer to the Batch Status API for more information.

---

1. Invocation Method

Invocation Method

• HTTP Method: POST
• Content-Type: application/x-www-form-urlencoded
• Request URL: https://api.paasoo.com/batch_json

Important Notes

• The number of messages per batch request must be between 1 and 5,000. Exceeding this limit will return an error status code.
• Perform deduplication and validity checks on batch numbers to reduce failures caused by invalid or duplicate numbers.
• Before large-scale sending, it is recommended to validate the template and parameters in a test environment or on a small scale to ensure correctness.

---

2. Request Format

Below is a typical example using a POST request, where parameters must be passed in the request body in URL-encoded (application/x-www-form-urlencoded) format:

cURL

curl -X POST "https://api.paasoo.com/batch_json" \ 
-H "Content-Type: application/x-www-form-urlencoded" \ 
-d "key=API_KEY&secret=API_SECRET&from=TEST&to=12025550123,12025550124&text=This+is+test+sms+from+TEST"

In the above example:

• The to parameter accepts multiple comma-separated numbers, such as 12025550123,12025550124.
• The text parameter is URL-encoded, where This+is+test+sms+from+TEST represents the actual SMS content.
• Please ensure you replace key and secret with the credentials obtained from the PaaSoo console, and keep them secure.

---

3. Request Parameters

Among the following parameters, those marked as "India only" are only applicable when sending to local Indian numbers (or using local Indian carrier routes); do not fill them in for other countries/regions, otherwise the delivery may fail.

Parameter	Type	Required	Description	Example
key	string	Yes	API Key (composed of 8 alphanumeric characters), used to uniquely identify your account. Can be obtained in the PaaSoo client console.	Abcdefgh
secret	string	Yes	API Secret (composed of 8 alphanumeric characters), used in conjunction with key for authentication. Can be obtained in the PaaSoo client console.	Abc123EF
from	string	Yes	Sender ID displayed for the SMS. Customization is only supported in certain countries/regions and may have length or character restrictions. To use a specific Sender ID, please contact your account manager or technical support (support@paasoo.com).	TEST
to	string	Yes	Destination Number, in the format Country Code + Mobile Number (without leading 00 or +). Supports 1 - 5000 mobile numbers; Multiple numbers are separated by commas (,); It is recommended to verify number compliance before submitting.	12025550123,12025550124
text	string	Yes	SMS content (must be URL Encoded). If the string length exceeds the limit, it may be split into multiple messages, incurring additional charges.	This is test sms from TEST
peid	string	No	Principal Entity ID for Indian templates. India only. You must register on the Indian DLT platform and apply for activation with your account manager.	1401480220000021629
templateid	string	No	Indian Template ID. India only. Corresponds to the template name on the DLT platform. You must complete registration and contact your account manager for activation.	1407160568716357486

Note:

• The display of from is subject to local operator policies in different countries or network environments.
• When text contains spaces or special characters, URL encoding is required.
• For security reasons, never expose your API Key and API Secret in frontend applications or public locations.
• If you need to send a higher volume of messages, you can call this API multiple times to achieve large-scale sending.

---

4. Response Parameters

When a batch SMS request is successful, it returns batch-level status information along with the sending results for each individual number. You can use the batchid for subsequent queries, statistics, or tracking.

Parameter	Type	Description	Example
status	integer	The processing result of the entire batch. 0 indicates the request was successfully received and processed.	0
status_code	string	Response status description. The status code submitted to the PaaSoo cloud communication platform. Generally, 0 represents success.	Invalid credentials
batchid	string	Batch request ID. A globally unique value generated for each request, used for subsequent queries or statistics.	a0018f-e4bf51-e000
data	array	A list of sending details corresponding to the batch numbers, including the processing result for each number.	[...]

Each element in the data array:

Parameter	Type	Description	Example
to	string	Destination Number of the SMS.	12025550123
messageid	string	Message ID, used to distinguish individual SMS sending records.	00018f-e4bf51-e002
status	integer	The sending status code for a single number. 0 represents success.	0
status_code	string	The error reason or description for that number, which helps in troubleshooting.	Missing parameters

Below are common response examples:

4.1 Success Example

{ 
    "status": 0, 
    "status_code": "success", 
    "batchid": "a0018f-e4bf51-e000", 
    "data": [
        { 
            "status": 0,
            "to": "12025550123",
            "messageid": "00018f-e4bf51-e002"
        },
        {
            "status": 0,
            "to": "12025550124",
            "messageid": "00018f-e4bf51-e003"
        }
    ]
}

4.2 Failure Example

{ "status": 4, "status_code": "Invalid credentials."}

---

5. API Status Codes

• 0 - success: Success
• 2 - Missing parameters: Required parameters are missing
• 3 - Invalid parameters: Parameter format error
• 4 - Invalid credentials: API Key or API Secret error
• 5 - Unauthorized IP: IP Whitelist restriction
• 6 - Invalid phone number: Number format error
• 7 - Invalid sender id: from parameter format error
• 8 - Message bombing detected: Repeated requests within 3 seconds
• 9 - Quota exceeded: Insufficient Balance or credit limit
• 10 - Throttling error: Rate limit exceeded
• 11 - System error: System error
• 14 - Nb of messages per request should be between 1 and 5000
• 19 - Invalid peid / Invalid templateid

This API provides extremely high sending elasticity by default. If you receive the error code status=10 during invocation, it means your account has a custom rate limit enabled according to your business agreement. If you need to adjust the Throttling threshold, please contact your account manager or the PaaSoo technical support team (support@paasoo.com).

---

6. Code Examples

Below are simple examples of how to integrate the "Batch SMS API" across various mainstream programming languages.

Python

import requests

# API Endpoint
url = "https://api.paasoo.com/batch_json"

# Form data
payload = {
    "key": "API_KEY",                         # Replace with your API Key
    "secret": "API_SECRET",                   # Replace with your API Secret
    "from": "TEST",                           # Sender ID
    "to": "12025550123,12025550124",          # Destination Numbers, separated by commas
    "text": "This is a test SMS from TEST"    # SMS content
}

# Request headers
headers = {
    "Content-Type": "application/x-www-form-urlencoded"
}

try:
    # Send HTTP POST request
    response = requests.post(url, data=payload, headers=headers)
    response.raise_for_status()
    
    # Parse and print JSON response
    data = response.json()
    if data.get("status") == 0:
        print("Batch SMS sent successfully, batchid:", data.get("batchid"))
    else:
        print(f"Batch SMS sending failed, status: {data.get('status')}, message: {data.get('status_code')}")

except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Node.js

const axios = require('axios'); // Run: npm install axios

// API Endpoint
const url = 'https://api.paasoo.com/batch_json';

// Prepare URL-encoded form data
const data = new URLSearchParams({
    key: 'API_KEY',                      // Replace with your API Key
    secret: 'API_SECRET',                // Replace with your API Secret
    from: 'TEST',                        // Sender ID
    to: '12025550123,12025550124',       // Destination Numbers, separated by commas
    text: 'This is a test SMS from TEST' // SMS content
});

// Send HTTP POST request
axios.post(url, data.toString(), {
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    }
})
.then((response) => {
    const result = response.data;
    if (result.status === 0) {
        console.log('Batch SMS sent successfully, batchid:', result.batchid);
    } else {
        console.log('Batch SMS sending failed, status:', result.status, 'message:', result.status_code);
    }
})
.catch((error) => {
    console.error('Request failed:', error.message || error);
});

PHP

<?php

// API Endpoint
$url = "https://api.paasoo.com/batch_json";

// Request parameters
$data = [
    "key" => "API_KEY",                    // Replace with your API Key
    "secret" => "API_SECRET",              // Replace with your API Secret
    "from" => "TEST",                      // Sender ID
    "to" => "12025550123,12025550124",     // Destination Numbers, separated by commas
    "text" => "This is a test SMS from TEST" // SMS content
];

// Initialize cURL session
$ch = curl_init($url);

// Set cURL options for POST and x-www-form-urlencoded
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/x-www-form-urlencoded"
]);

// Execute request
$response = curl_exec($ch);

if($e = curl_error($ch)) {
    echo "Request failed: " . $e;
} else {
    $result = json_decode($response, true);
    if (isset($result['status']) && $result['status'] === 0) {
        echo "Batch SMS sent successfully, batchid: " . $result['batchid'] . "\n";
    } else {
        echo "Batch SMS sending failed, status: " . $result['status'] . ", message: " . $result['status_code'] . "\n";
    }
}

// Close cURL session
curl_close($ch);
?>

Java

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.FormBody;
import okhttp3.Response;
import java.io.IOException;

// Make sure to add OkHttp dependency in your pom.xml or build.gradle
public class BulkSmsApiExample {
    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient();

        // Build x-www-form-urlencoded request body
        RequestBody formBody = new FormBody.Builder()
                .add("key", "API_KEY")                          // Replace with your API Key
                .add("secret", "API_SECRET")                    // Replace with your API Secret
                .add("from", "TEST")                            // Sender ID
                .add("to", "12025550123,12025550124")           // Destination Numbers
                .add("text", "This is a test SMS from TEST")    // SMS content
                .build();

        // Build request
        Request request = new Request.Builder()
                .url("https://api.paasoo.com/batch_json")
                .post(formBody)
                .addHeader("Content-Type", "application/x-www-form-urlencoded")
                .build();

        // Execute request
        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                System.out.println("Response: " + response.body().string());
            } else {
                System.out.println("Request failed, status code: " + response.code());
            }
        } catch (IOException e) {
            System.err.println("Request failed: " + e.getMessage());
        }
    }
}

Go

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
    "strings"
)

func main() {
    apiURL := "https://api.paasoo.com/batch_json"

    // Prepare form data
    data := url.Values{}
    data.Set("key", "API_KEY")                          // Replace with your API Key
    data.Set("secret", "API_SECRET")                    // Replace with your API Secret
    data.Set("from", "TEST")                            // Sender ID
    data.Set("to", "12025550123,12025550124")           // Destination Numbers
    data.Set("text", "This is a test SMS from TEST")    // SMS content

    // Send HTTP POST request
    req, err := http.NewRequest("POST", apiURL, strings.NewReader(data.Encode()))
    if err != nil {
        fmt.Println("Error creating request:", err)
        return
    }
    req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Request failed:", err)
        return
    }
    defer resp.Body.Close()

    // Read response body
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Error reading response:", err)
        return
    }

    // Parse JSON
    var result map[string]interface{}
    if err := json.Unmarshal(body, &result); err != nil {
        fmt.Println("Error parsing JSON:", err)
        return
    }

    // Check status (Note: In Go, JSON numbers are parsed as float64 by default)
    if status, ok := result["status"].(float64); ok && status == 0 {
        fmt.Println("Batch SMS sent successfully, batchid:", result["batchid"])
    } else {
        fmt.Printf("Batch SMS sending failed, status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

Any language or framework supporting HTTP/HTTPS can easily integrate by using the same POST method and requesting with application/x-www-form-urlencoded.

---

7. Best Practices

1. Number Validation & Cleansing: Remove invalid or duplicate numbers before batch sending to minimize waste and errors caused by invalid numbers.
2. Follow Frequency Limits: Avoid sending too many messages at once in a very short time. If there is a massive volume requirement, you can call the API multiple times.
3. Content & Encoding: SMS content should be URL encoded. Pay extra attention to billing or costs when excessively long content is split into multiple parts.
4. Sending Logs & Monitoring: Record the batchid on your backend and save the status and messageid (Message ID) for each SMS to facilitate tracking.
5. Retry & Idempotency: In case of network fluctuations or other anomalies, you can set up a retry mechanism and use a unique request ID to prevent duplicate sending.
6. Data Security & Compliance: Comply with privacy and SMS sending regulations of the destination countries or regions (e.g., operator policies). For marketing SMS, prior user consent must be obtained.

By following the above steps and best practices, you can quickly implement bulk SMS sending to users worldwide. If you need to understand the delivery results or success rates of your batch messages, please refer to the Batch Status API for more details.

Support

If you encounter any technical issues or have business inquiries during the API integration, please do not hesitate to contact our Support team at support@paasoo.com. We are always here to assist you.