SMS API

Welcome to the PaaSoo SMS API service! With this API, you can quickly send single SMS messages to users worldwide, meeting the needs of various business scenarios such as identity verification, marketing promotions, and order notifications. PaaSoo provides a global SMS service, ensuring efficient and reliable message delivery through direct connections with carriers and years of industry experience. This guide provides comprehensive and detailed instructions, parameter explanations, examples, and best practices for using the API, helping you seamlessly integrate and fully utilize our SMS API service.

1. API Overview

Supports sending international SMS covering 200+ countries and regions, including scenarios like verification codes, service notifications, and marketing (specific coverage is subject to carrier routing). Through this API, you can:

Send SMS to mobile users worldwide.
Set a custom Sender ID (the availability of this feature depends on the destination country's operator policies).
Track message delivery results, status changes, and error reasons.
Flexibly integrate into your applications, websites, or backend services.

Note

Due to differences in operator regulations and network protocols across countries, some countries or regions may not support custom Sender IDs or other advanced features. If you need such custom features, please contact your account manager or send your inquiry to: support@paasoo.com.

2. Invocation Method

Invocation Method

HTTP Method: GET
Request URL: https://api.paasoo.com/json

Before calling this API, please ensure you have obtained your API Key and API Secret from the user console. Both must be included as query parameters in your request.

Recommendation

To ensure data confidentiality and security, we strongly recommend using the HTTPS protocol when calling the API to prevent eavesdropping or tampering during transmission.

3. Request Example

The simplest example involves sending an HTTP GET request with the necessary parameters:

https://api.paasoo.com/json?key=API_KEY&secret=API_SECRET&from=TEST&to=12025550123&text=This+is+test+sms+from+TEST

The text parameter in the above example has been URL-encoded. Please make sure to apply the correct encoding in your actual implementation.

4. 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), your unique identifier. Can be obtained in the client console. Please keep it safe.	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 +). For example, a US number is written as 12025550123.	12025550123
text	string	Yes	The SMS content, which must be UTF-8 encoded and URL-encoded. For simple testing, you can use third-party tools or auto-encoding in your backend.	This is test sms from TEST
requestId	string	No	A unique request ID used to identify the request for tracking and troubleshooting. To ensure idempotency, please use a different `requestId` for each request; If the same request ID is used within 60 seconds, it is treated as the same request. The system will return the same response as the first request without deducting fees or sending the message again.	0432258a-ecc7-4628-9158-2b883fe65181
peid	string	No	Principal Entity ID for Indian templates. India only. To send SMS in India and use this parameter, you must register on the Indian DLT platform and contact your account manager for activation.	1401480220000021629
templateid	string	No	Indian Template ID. India only. To send SMS in India and use this parameter, you must register on the Indian DLT platform and contact your account manager for activation.	1407160568716357486
ref	string	No	Custom parameter defined by the client, used to correlate the initial request with PaaSoo's response (returned via asynchronous notification or query results).

Attention

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 key and 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.

5. Response Parameters

On success, the API returns a status code along with the corresponding Message ID. On failure, it returns the relevant error status code and description.

Parameter	Type	Description	Example
messageid	string	Message ID, the unique identifier for each SMS record.	015bd4-d6dfa7-58w
status	string	Response status. The status code submitted to the PaaSoo cloud communication platform. Generally, "0" represents success.	"0" - success
status_code	string	Status description, used to explain the error reason or provide detailed status info.	Missing parameters

5.1 Success Response Example

{ "status": "0", "messageid": "015bd4-d6dfa7-58w"}

5.2 Failure Response Example

{ "status": "2", "status_code": "Missing parameters."}

6. 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
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).

7. Code Examples

The following provides code examples in various programming languages to help you quickly integrate into your existing systems:

Python
Node.js
PHP
Java
Go

import requests

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

# Query Parameters
params = {
    "key": "API_KEY",                # Replace with your API Key
    "secret": "API_SECRET",          # Replace with your API Secret
    "from": "TEST",                  # Sender ID
    "to": "12025550123",             # Destination Number
    "text": "This is a test SMS from TEST"
}

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

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

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

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

// Query Parameters
const params = {
    key: 'API_KEY',               // Replace with your API Key
    secret: 'API_SECRET',         // Replace with your API Secret
    from: 'TEST',                 // Sender ID
    to: '12025550123',            // Destination Number
    text: 'This is a test SMS from TEST',
};

// Send HTTP GET request
axios.get(url, { params })
    .then((response) => {
        const data = response.data;
        if (data.status === '0') {
            console.log('SMS sent successfully, messageid:', data.messageid);
        } else {
            console.log('SMS sending failed, status:', data.status, 'message:', data.status_code);
        }
    })
    .catch((error) => {
        console.error('Request failed:', error.message || error);
    });

<?php

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

// Query Parameters
$params = [
    "key" => "API_KEY",             // Replace with your API Key
    "secret" => "API_SECRET",       // Replace with your API Secret
    "from" => "TEST",               // Sender ID
    "to" => "12025550123",          // Destination Number
    "text" => "This is a test SMS from TEST"
];

// Build query string and append to URL
$queryString = http_build_query($params);
$requestUrl = $url . '?' . $queryString;

// Initialize cURL session
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $requestUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

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

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

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.HttpUrl;
import java.io.IOException;

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

        // Build URL with query parameters
        HttpUrl.Builder urlBuilder = HttpUrl.parse("https://api.paasoo.com/json").newBuilder();
        urlBuilder.addQueryParameter("key", "API_KEY");         // Replace with your API Key
        urlBuilder.addQueryParameter("secret", "API_SECRET");   // Replace with your API Secret
        urlBuilder.addQueryParameter("from", "TEST");           // Sender ID
        urlBuilder.addQueryParameter("to", "12025550123");      // Destination Number
        urlBuilder.addQueryParameter("text", "This is a test SMS from TEST");

        String url = urlBuilder.build().toString();

        // Build request
        Request request = new Request.Builder()
                .url(url)
                .get()
                .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());
        }
    }
}

package main

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

func main() {
    // Parse base URL
    baseURL, err := url.Parse("https://api.paasoo.com/json")
    if err != nil {
        fmt.Println("URL parsing error:", err)
        return
    }

    // Add query parameters
    params := url.Values{}
    params.Add("key", "API_KEY")             // Replace with your API Key
    params.Add("secret", "API_SECRET")       // Replace with your API Secret
    params.Add("from", "TEST")               // Sender ID
    params.Add("to", "12025550123")          // Destination Number
    params.Add("text", "This is a test SMS from TEST")

    // Encode parameters and append to URL
    baseURL.RawQuery = params.Encode()

    // Send HTTP GET request
    resp, err := http.Get(baseURL.String())
    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("JSON parsing error:", err)
        return
    }

    // Check status
    if status, ok := result["status"].(string); ok && status == "0" {
        fmt.Println("SMS sent successfully, messageid:", result["messageid"])
    } else {
        fmt.Printf("SMS sending failed, status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

Since this API relies entirely on HTTP requests, you can implement it in any language or framework that supports HTTP/HTTPS. Just follow the same query parameter construction logic.

8. Delivery Reports and Status Callbacks

In some scenarios, you may need to obtain the final delivery status of the SMS or the reason for rejection (e.g., Unreachable numbers, disconnected users, etc.). You can view the delivery status in the client console, or through the following methods:

Call the Message Status API to get real-time delivery results of your SMS.
Configure a Webhook URL to receive asynchronous SMS Delivered or Failed reports via the Callback URL For Delivery Receipts.

For specific details on how to configure and use these methods, please refer to the corresponding documentation.

9. Best Practices

Parameter Security: Securely store and use your API Key and API Secret on the backend, and never expose them on the frontend.
Throttling: The PaaSoo platform defaults to no unified concurrency limits to support the rapid growth of our clients' businesses. However, in specific scenarios, to ensure account security or per contract terms, we can configure custom QPS (Queries Per Second) Throttling for you. If you anticipate an explosive growth in volume, please notify your account manager in advance to ensure sufficient carrier resources.
Content Compliance: Comply with local operator regulations, avoid sending sensitive, illegal, or inappropriate content to prevent account suspension.
Encoding and Length Control: When using non-Latin characters, the SMS content will likely be sent in Unicode, meaning a lower maximum character length; please review the difference between GSM 7-bit and Unicode encoding.
Testing Environment: Before formally deploying to the production environment, it is recommended to test thoroughly on test numbers or a sandbox environment to ensure correct integration.
Monitoring and Logging: Establish log levels and monitoring alert mechanisms to detect sending volumes and Delivery Rates in a timely manner.
Idempotency Design: To ensure the same SMS is sent only once, generate a unique requestId for each request, and implement deduplication on your server.

10. FAQ

Why is my Sender ID not working?

Possible reasons include specific Sender ID restrictions in the destination country, Local Operator requirements for pre-registration, or operator policy limitations. If you need a customized Sender ID, please contact your account manager for more details.

Can I send content containing Chinese, Japanese, or emojis?

Yes, but you must ensure it is encoded in UTF-8 and URL-encoded. Non-GSM characters take up more character space and may trigger message concatenation or length restrictions.

Why did I receive "status = 9 / Quota exceeded"?

This indicates your account Balance is insufficient or your credit limit has been exhausted. Please top up in time or contact sales to increase your limit.

How do I get the final Delivered or Failed reasons for my SMS?

You can query delivery reports directly in the management console, call the Message Status API, or configure a Webhook URL to receive status updates via the Callback URL For Delivery Receipts.

How can I send Batch SMS?

We recommend using our Batch SMS API or calling the single SMS API in batches with concurrency or queue controls implemented on your end. For more details, refer to our Batch SMS API documentation.

11. Appendix

Unicode vs. GSM 7-bit Encoding:
- GSM 7-bit Encoding:
  - Within 160 characters: Billed as 1 message.
  - Over 160 characters: Split and billed at 153 characters/message (reserving 7 characters for the User Data Header/UDH for concatenation).
- Unicode Encoding:
  - Within 70 characters: Billed as 1 message.
  - Over 70 characters: Split and billed at 67 characters/message.
Concatenated SMS:
- Once the message length exceeds the maximum character limit, the carrier will split and send the SMS. Generally, the platform will automatically handle the splitting, sorting, and concatenating, which may incur additional Billing Count charges.
DLT Registration (India):
- Due to Indian telecom regulations, all entities sending marketing or corporate SMS must register on the DLT platform.
- If you need to send local SMS in India and support parameters like Template ID and PEID, you must comply with local policies.
IP Whitelist and Security:
- If your account has an IP Whitelist configured, ensure the source IP of your API requests is within the whitelist to avoid triggering status = 5 (Unauthorized IP).

Important Notice

Due to differences in Billing logic across global operators and routing channels, the lengths mentioned above are for reference only. Actual Billing Count will depend on the destination country operator's settlement rules and the final Billing records or invoices provided by the PaaSoo system.
It is recommended to observe actual Billing deductions via test numbers before launching large-scale sending.

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.

1. API Overview​

2. Invocation Method​

3. Request Example​

4. Request Parameters​

5. Response Parameters​

5.1 Success Response Example​

5.2 Failure Response Example​

6. API Status Codes​

7. Code Examples​

8. Delivery Reports and Status Callbacks​

9. Best Practices​

10. FAQ​

11. Appendix​