Getting Started

Preparation

To meet the requirements of relevant departments, you must complete the following operations in the console before using the Skynoo SMS service.

Real Name Authentication

According to the requirements of the operator gateway, sending SMS requires real-name authentication. Unauthenticated individuals, enterprises, and organizations do not support custom template submissions and can only send ordinary verification code SMS.

Add SMS Template

Go to the console "International SMS-Template Reporting" to add a template. You can customize the template code to increase the readability of the template identifier. Notes:

1. The total length of the SMS body must be controlled within 460 characters. Special symbols such as 【】 and ★, ※, →, ●, etc., are not supported.
2. Variables are represented by #variable_name#, such as #code# #order_no#. Variable names are strings composed of letters, numbers, and underscores, with a length of less than 24 characters. The same variable can only appear once in the template. The format of short links combined with variables directly is not supported.

Generate API Credentials

Go to Console "API Credentials" section to generate apiKey and apiSecret for API authentication.

Send SMS

After completing the above work, you can call the SMS APIs:

• Single SMS: Use Send SMS API for sending to one recipient
• OTP Verification: Use OTP Verification APIs for verification code scenarios
• Batch SMS: Use Batch SMS API for sending to multiple recipients asynchronously

Regions and Access Points

API Authentication

All API requests require authentication via the Authorization header using apiKey:apiSecret encoded in Base64.

Authorization Header Format

Authorization: Basic {Base64(apiKey:apiSecret)}

How to Generate Authorization Header

1. Generate apiKey and apiSecret in Console "API Credentials" section

   apiKey format: app_xxxxx, apiSecret format: sec_xxxxx

2. Combine apiKey and apiSecret with colon separator:

   apiKey:apiSecret

3. Encode the combination with Base64:

   Base64.getEncoder().encodeToString((apiKey + ":" + apiSecret).getBytes())

4. Add "Basic " prefix and use in Authorization header:

   curl -H "Authorization: Basic YXBwXzEyMzq6c2VjXzEyMzQ1Njc4OTA="

Example Request

curl -X POST 'https://api.skynoo.com/api/sms/v1/send' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YXBwXzEyMzq6c2VjXzEyMzQ1Njc4OTA=' \
-d '{"mobile": "+8613800138000", "useType": 1, "text": "Your code is 123456"}'

Security Best Practices

• Never expose apiSecret in client-side code or public repositories
• Store apiSecret securely and rotate periodically
• Use HTTPS for all API requests
• Implement IP whitelist in Console for additional security

Send SMS API (Single)

Use this interface to send a single SMS to one recipient. Supports verification code (OTP), notification, and marketing SMS types.

Interface Definition

• Interface Name: /api/sms/v1/send
• HTTP Method: POST
• Content-Type: application/json

Request Parameters

Request Examples

Send Verification Code (useType=1)

curl -X POST 'https://api.skynoo.com/api/sms/v1/send' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YXBwXzEyMzq6c2VjXzEyMzQ1Njc4OTA=' \
-d '{
  "mobile": "+8613800138000",
  "useType": 1,
  "text": "Your verification code is 123456, valid for 5 minutes."
}'

Send Notification with Template (useType=2)

curl -X POST 'https://api.skynoo.com/api/sms/v1/send' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YXBwXzEyMzq6c2VjXzEyMzQ1Njc4OTA=' \
-d '{
  "mobile": "+8613800138000",
  "useType": 2,
  "templateId": 15,
  "data": {"orderNo": "ORD-2024-001", "status": "shipped"}
}'

Response Parameters

Response Example

{
  "code": "200",
  "message": "Request successful",
  "data": {
    "id": "8fc02cb2dbcdc500bf4056330bd6a312",
    "toNumber": "+8613800138000",
    "status": "pending"
  }
}

OTP Verification APIs

OTP (One-Time Password) verification APIs provide a complete lifecycle management for verification code scenarios including login, registration, password reset, etc.

Use Cases

• User Registration: Verify new user phone numbers
• Login Authentication: Two-factor authentication (2FA)
• Password Reset: Verify identity before password change
• Transaction Verification: Secure payment or sensitive operations
• Account Binding: Link phone number to existing account

Workflow

1. Call Send Verification Code API with user's mobile number
2. System generates code, sends SMS, and returns verifyId
3. User receives SMS and enters the code in your application
4. Call Verify Code API with verifyId and user-entered code
5. System validates and returns verification result

Send Verification Code API

Interface Definition

• Interface Name: /api/sms/v1/verification/send
• HTTP Method: POST
• Content-Type: application/json

Request Parameters

Request Example

curl -X POST 'https://api.skynoo.com/api/sms/v1/verification/send' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YXBwXzEyMzq6c2VjXzEyMzQ1Njc4OTA=' \
-d '{
  "mobile": "+8613800138000",
  "codeLength": 6,
  "expireMinutes": 5,
  "scene": "login"
}'

Response Parameters

Response Example

{
  "code": "200",
  "message": "Request successful",
  "data": {
    "verifyId": "v_abc123def456",
    "expireTime": 1700000000000
  }
}

Rate Limits

• Same mobile number: 60 seconds interval between sends
• Same account: 100 verification codes per hour

Verify Code API

Interface Definition

• Interface Name: /api/sms/v1/verification/check
• HTTP Method: POST
• Content-Type: application/json

Request Parameters

Request Example

curl -X POST 'https://api.skynoo.com/api/sms/v1/verification/check' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YXBwXzEyMzq6c2VjXzEyMzQ1Njc4OTA=' \
-d '{
  "verifyId": "v_abc123def456",
  "mobile": "+8613800138000",
  "code": "123456"
}'

Response Parameters

Response Examples

Success - Code Valid

{
  "code": "200",
  "message": "Request successful",
  "data": {
    "valid": true,
    "remainingAttempts": 0
  }
}

Success - Code Invalid

{
  "code": "200",
  "message": "Request successful",
  "data": {
    "valid": false,
    "remainingAttempts": 2
  }
}

Failed - Code Expired

{
  "code": "400",
  "message": "Verification code expired"
}

Failed - Max Attempts Reached

{
  "code": "400",
  "message": "Verification code exhausted"
}

Verification States

Batch SMS API

Use Batch SMS API to send SMS to multiple recipients asynchronously, the system processes the task in background.

Create Batch Task API

Interface Definition

• Interface Name: /api/sms/v1/batch/create
• HTTP Method: POST
• Content-Type: application/json

Request Parameters

Request Example

curl -X POST 'https://api.skynoo.com/api/sms/v1/batch/create' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YXBwXzEyMzq6c2VjXzEyMzQ1Njc4OTA=' \
-d '{
  "useType": 2,
  "content": "Your order #order_no# has been shipped.",
  "numbers": ["+8613800138000", "+8613900139000"],
  "templateData": {
    "+8613800138000": {"order_no": "A001"},
    "+8613900139000": {"order_no": "A002"}
  }
}'

Response Parameters

Response Example

{
  "code": "200",
  "message": "Request successful",
  "data": {
    "taskId": 1001,
    "status": "pending"
  }
}

Query Task Status API

Interface Definition

• Interface Name: /api/sms/v1/batch/status
• HTTP Method: POST

Request Parameters

Response Parameters

Response Example

{
  "code": "200",
  "message": "Request successful",
  "data": {
    "taskId": 1001,
    "status": "success"
  }
}

Query Task Details API

Interface Definition

• Interface Name: /api/sms/v1/batch/detail
• HTTP Method: POST

Request Parameters

Response Example

{
  "code": "200",
  "message": "Request successful",
  "data": {
    "records": [
      {
        "id": "sms_record_001",
        "toNumber": "+8613800138000",
        "status": "DELIVERED",
        "errorCode": "",
        "sendTime": 1700000000000
      }
    ],
    "total": 2,
    "pageNo": 1,
    "pageSize": 20
  }
}

Get SMS Status API

Use this interface to query the delivery status of sent SMS messages. Query up to 100 messages per request.

Interface Definition

• Interface Name: /api/sms/v1/getStatus
• HTTP Method: POST
• Content-Type: application/json

Request Parameters

Request Example

curl -X POST 'https://api.skynoo.com/api/sms/v1/getStatus' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YXBwXzEyMzq6c2VjXzEyMzQ1Njc4OTA=' \
-d '{
  "ids": ["8fc02cb2dbcdc500bf4056330bd6a312", "8fc02cb2dbcdc500bf4099330bd6a312"]
}'

Response Parameters

Message Status Values

Response Example

{
  "code": "200",
  "message": "Request successful",
  "data": [
    {
      "sid": "8fc02cb2dbcdc500bf4056330bd6a312",
      "status": "DELIVERED",
      "errorCode": ""
    },
    {
      "sid": "8fc02cb2dbcdc500bf4099330bd6a312",
      "status": "REJECTED",
      "errorCode": "BLOCKED"
    }
  ]
}