HTTP API

API Documentation

SMS provides a simple REST API for sending SMS worldwide.

POST/api/send

Data centers and API endpoints

China Mainland: https://sms-cn.maiyun.net
Asia South: https://sms-as.maiyun.net

Use the API endpoint for the data center where your resources and Token reside, regardless of interface language or recipient region.

Authentication

All requests must include Authorization: Bearer YOUR_API_KEY in the header. Obtain your API Key from the console.

POST/api/sendSend SMS

Request Parameters

Parameter	Type	Required	Description
area	string	Required	Recipient region. Currently only cn (China Mainland) is supported, independently of the API data center.
phone	number	Required	Local recipient phone number without a country calling code, submitted as a JSON number, e.g. 13800138000 without quotes. Specify the recipient region using area.
sign	string	Required	UID of an approved signature belonging to your tenant. Required for China Mainland. Replace YOUR_APPROVED_SIGN_UID with the actual UID.
text	string	Required	The body must match an approved template belonging to your tenant. Do not prepend the signature yourself. Maximum 60 UTF-16 code units for the body and 70 including 【signature】. Overlength messages are rejected, not split.

Request example

JavaScript

// Set the API endpoint for your data center.
const API_BASE = 'https://sms-cn.maiyun.net';

fetch(API_BASE + '/api/send', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        area: 'cn',
        phone: 13800138000,
        sign: 'YOUR_APPROVED_SIGN_UID',
        text: 'Your verification code is 123456, valid for 5 minutes.',
    })
})
.then(r => r.json())
.then(data => {
    console.log(data.result); // => 1
    console.log(data.uid);
});

Response Fields

Field	Type	Description
result	number	1 indicates a successful API call; 0 or a negative value indicates failure.
uid	string	Unique sending record UID returned on a successful API call.
msg	string	Error description returned on failure. Interpret it together with result.

Success Response

JSON

{
    "result": 1,
    "uid": "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01"
}

Error Response

JSON

{
    "result": -400,
    "msg": "Param error: phone"
}

Error Codes

Code	Description
-4	Insufficient available account balance.
-5	No approved template matches, or the selected signature is missing, unapproved, or unavailable.
-7	The body did not pass content review.
-8	The recipient region is unsupported. Currently only cn is supported.
-9	The body exceeds 60 UTF-16 code units, or the complete message including its signature exceeds 70.
-400	A request parameter is missing or invalid, including a missing signature for China Mainland recipients.
-401	No valid Session and no Authorization header were provided.
-402	The Bearer Token has an invalid format, does not exist, is unavailable, or has been deleted.
-403	The tenant does not exist or is disabled, or this host does not accept the request. Use the API endpoint for your data center.
-406	The Session request failed XSRF validation. Refresh the page before trying again.
-429	Request rate limit exceeded. Please try again later.
-5xx	System error.

A result of 1 indicates a successful API call. Failed calls return an error code from the table above.