RedsmsBox

Developer docs

A RESTful API authenticated with an access token, with UTF-8 JSON for both requests and responses. Every endpoint below comes with a curl example you can run as is.

SMS API — send messages

Trigger sends directly from your own systems. to takes a single number, or several separated by commas (up to 1000 per call); once accepted the call returns a message_id you can use to check delivery status.

Authentication headers
Parameter
Required
Description
Authorization
Yes
Send your API token with the Bearer scheme, for example:Authorization: Bearer {api_token}
Accept
Yes
Set to application/json

Send a message

Send a text message to one or more numbers. In the response, segments is how many messages this send occupies and cost is its total.

Endpoint

POST https://redsmsbox.com/api/v1/sms/send

Parameter

Parameter
Required
Type
Description
to
Yes
string
Recipient number in E.164 format (with country code); separate multiple numbers with commas
message
Yes
string
Message body. For China, the format is 【signature】text, and marketing content must end with an opt-out line
channel
No
string
Route ID; falls back to the account default
sender_id
No
string
Custom sender identifier (Sender ID) for international messages
schedule_at
No
string
Scheduled send time (ISO 8601 UTC); sends immediately if omitted
callback_url
No
string
Webhook URL for this message's status receipt, overriding the account default

Example request

curl -X POST https://redsmsbox.com/api/v1/sms/send \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "to": "+8613800138000",
  "message": "【RedsmsBox】您的验证码是 123456，5 分钟内有效。"
}'

Response

{
  "ok": true,
  "message_id": "msg_3f7a91",
  "status": "queued",
  "to": "+8613800138000",
  "segments": 1,
  "cost": "0.06",
  "currency": "USD"
}
{
    "ok": false,
    "error_code": "invalid_parameter",
    "error": "The body is not valid JSON, or a field failed validation"
}

Failed responses always use this envelope. The error field is always English and does not follow the interface language — it is meant for machines and log aggregation. Branch on error_code; never match against the text of error. The full code table lives in the console developer docs.

Check delivery status

Look up a single message's current status and carrier receipt time by the message_id returned when it was sent.

Endpoint

GET https://redsmsbox.com/api/v1/sms/{message_id}

Parameter

Parameter
Required
Type
Description
message_id
Yes
string
The message ID returned by the send endpoint

Example request

curl -X GET https://redsmsbox.com/api/v1/sms/msg_3f7a91 \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'

Response

{
  "ok": true,
  "message_id": "msg_3f7a91",
  "status": "delivered",
  "to": "+8613800138000",
  "segments": 1,
  "cost": "0.06",
  "currency": "USD",
  "submitted_at": "2026-08-16T09:12:31Z",
  "delivered_at": "2026-08-16T09:12:34Z"
}
{
    "ok": false,
    "error_code": "invalid_parameter",
    "error": "The body is not valid JSON, or a field failed validation"
}

Failed responses always use this envelope. The error field is always English and does not follow the interface language — it is meant for machines and log aggregation. Branch on error_code; never match against the text of error. The full code table lives in the console developer docs.

List sent messages

Page through this account's sending history, filtered by time and status.

Endpoint

GET https://redsmsbox.com/api/v1/sms

Parameter

Parameter
Required
Type
Description
status
No
string
Filter by status, e.g. queued / delivered / failed
start
No
string
Start time (ISO 8601 UTC)
end
No
string
End time (ISO 8601 UTC)
page
No
number
Page number, defaults to 1

Example request

curl -X GET 'https://redsmsbox.com/api/v1/sms?status=delivered&page=1' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'

Response

{
  "ok": true,
  "page": 1,
  "total": 2,
  "items": [
    {
      "message_id": "msg_3f7a91",
      "status": "delivered",
      "to": "+8613800138000",
      "segments": 1,
      "cost": "0.06"
    }
  ]
}
{
    "ok": false,
    "error_code": "invalid_parameter",
    "error": "The body is not valid JSON, or a field failed validation"
}

Failed responses always use this envelope. The error field is always English and does not follow the interface language — it is meant for machines and log aggregation. Branch on error_code; never match against the text of error. The full code table lives in the console developer docs.

Cannot find what you need? Talk to us

Describe your use case and support will come back with the permitted scope, a route recommendation and the rate.

Contact support