接入准备

发送规范

短信格式

正文可包含链接、地址，并支持换行。营销短信退订语当前仅支持“拒收请回复R”（不支持小写 r），且必须位于整条短信内容的最末尾；该规则后续可能随工信部政策调整。

发送时间限制

• 验证码（YZM 开头）、通知（N 开头）、会员营销（M 开头）三类账号默认无发送时间限制；但 M 账号在 22:00 之后发送成功率会明显下降，并可能被拦截，如有疑问请联系商务经理。
• 特殊类型账号默认发送时段为 08:00–20:00，不在该时段内提交的请求将被接口拦截并返回报错；如需调整发送时段，请联系商务经理。

模板 ID 发送接口

注意事项

• 如需状态回执，请传入 "report"="true"，否则无法获取状态回执。
• 调用接口返回错误时，请根据响应码提示检查请求参数及其取值是否正确，详见文末提交响应码说明。
• 更多发送问题，请查阅短信发送 FAQ。
• 如需了解计费规则，请查阅计费说明。
• 账户提供默认余额提醒，详情请查阅余额提醒文档。

请求地址

• 请求方式：POST
• Content-Type：application/json
• 编码格式：UTF-8
• 接口地址：https://smssh.253.com/msg/sms/v2/tpl/send

加密算法

• md5Password = API 密码的 MD5 值（32 位小写），即 md5(password)。
• 使用平台密钥 md5Password，与请求参数中的 timestamp、nonce 进行 HmacSHA256Hex 签名，生成 makeSignature，并通过请求头传递。

复制成功⧉
// 第三方工具类，需引入以下Maven依赖
import com.alibaba.fastjson.JSONObject;
import org.apache.commons.codec.digest.DigestUtils;
import org.apache.commons.codec.digest.HmacUtils;

public String makeSignature(String md5Password, String timestamp, String nonce) {
   String str = generateStr(md5Password, timestamp, nonce);
    return HmacUtils.hmacSha256Hex(md5Password, str.replaceAll("\\s+", ""));
}

/**
 * 签名待处理的字符串拼接
 */
public static String generateStr(String md5Password, String timestamp, String nonce){
    String[] array = new String[] { md5Password, timestamp, nonce};
    StringBuffer sb = new StringBuffer();
    // 字符串排序
    Arrays.sort(array);
    for (int i = 0; i < 3; i++) {
        sb.append(array[i]);
    }
    return sb.toString();
}

请求头参数

请求体参数

请求示例

复制成功⧉
请求头（Request Header）：
X-QA-Hmac-Signature: a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90
Content-Type: application/json

请求体（Body，使用加密鉴权，故不传 password）：
{
  "account": "N6000001",
  "timestamp": "1752143733",
  "nonce": "x4zfk0y5foqwx6cbnw3bfmimy98abqs1",
  "phoneNumbers": "17601337176,15100159057",
  "templateId": "1021143438",
  "templateParamJson": "[{\"param1\":\"张三\",\"param2\":\"13\"},{\"param1\":\"李四\",\"param2\":\"88\"}]",
  "signature": "【创蓝云智】",
  "report": "true",
  "callbackUrl": "https://your-domain.com/callback",
  "uid": "test_001",
  "extend": "01"
}

响应体参数

响应示例

复制成功⧉
{
  "code": "000000",
  "failNum": "0",
  "successNum": "2",
  "msgId": "25071018345400902898000000000001",
  "time": "20250710183454",
  "errorMsg": ""
}

多语言调用示例

Java

复制成功⧉
package send;

import com.alibaba.fastjson.JSONObject;
import org.apache.commons.codec.digest.DigestUtils;
import org.apache.commons.codec.digest.HmacUtils;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.*;

public class SmsClient {

    // 账号信息（建议后续通过配置或环境变量注入）
    private static final String ACCOUNT = "M122343";
    private static final String PASSWORD = "******";
    private static final String SEND_URL = "https://smssh.253.com/msg/sms/v2/tpl/send";

    public static void main(String[] args) {
        try {
            String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
            String nonce = UUID.randomUUID().toString().replace("-", "");

            // 构建模板参数
            List<Map<String, String>> templateParams = assembleTemplateParams();
            String templateParamJson = JSONObject.toJSONString(templateParams);

            // 构建请求参数
            Map<String, Object> requestMap = new HashMap<>();
            requestMap.put("account", ACCOUNT);
            requestMap.put("timestamp", timestamp);
            requestMap.put("nonce", nonce);
            requestMap.put("phoneNumbers", "15200000000,15100000000");
            requestMap.put("templateId", "1021143438");
            requestMap.put("templateParamJson", templateParamJson);
            requestMap.put("signature", "【222】");
            requestMap.put("report", "true");
            requestMap.put("callbackUrl", "");
            requestMap.put("uid", "test_001");
            requestMap.put("extend", "01");

            String jsonBody = JSONObject.toJSONString(requestMap);

            // 生成签名
            String md5Password = DigestUtils.md5Hex(PASSWORD);
            String signature = makeSignature(md5Password, timestamp, nonce);

            // 发送请求
            String response = sendSmsByPost(SEND_URL, jsonBody, signature);
            System.out.println("响应结果：" + response);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static List<Map<String, String>> assembleTemplateParams() {
        List<Map<String, String>> list = new ArrayList<>();

        Map<String, String> map1 = new HashMap<>();
        map1.put("param1", "张1");
        map1.put("param2", "张2");

        Map<String, String> map2 = new HashMap<>();
        map2.put("param1", "李1");
        map2.put("param2", "李2");

        list.add(map1);
        list.add(map2);

        return list;
    }

    public static String sendSmsByPost(String path, String postContent, String xQAHmacSignature) throws IOException {
        URL url = new URL(path);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setConnectTimeout(10000);
        conn.setReadTimeout(10000);
        conn.setDoOutput(true);
        conn.setDoInput(true);
        conn.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
        conn.setRequestProperty("X-QA-Hmac-Signature", xQAHmacSignature);

        try (OutputStream os = conn.getOutputStream()) {
            os.write(postContent.getBytes(StandardCharsets.UTF_8));
            os.flush();
        }

        int code = conn.getResponseCode();
        if (code != HttpURLConnection.HTTP_OK) {
            throw new IOException("HTTP 请求失败，状态码：" + code);
        }

        try (BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8))) {
            StringBuilder sb = new StringBuilder();
            String line;
            while ((line = br.readLine()) != null) {
                sb.append(line);
            }
            return sb.toString();
        }
    }

    public static String makeSignature(String md5Password, String timestamp, String nonce) {
        String str = generateStr(md5Password, timestamp, nonce);
        return HmacUtils.hmacSha256Hex(md5Password, str.replaceAll("\\s+", ""));
    }

    private static String generateStr(String md5Password, String timestamp, String nonce) {
        String[] array = new String[]{md5Password, timestamp, nonce};
        Arrays.sort(array);
        StringBuilder sb = new StringBuilder();
        for (String s : array) {
            sb.append(s);
        }
        return sb.toString();
    }
}

Python

复制成功⧉
import hashlib
import hmac
import json
import time
import uuid
import requests

# 账号信息（建议后续通过配置或环境变量注入）
ACCOUNT = "M122343"
PASSWORD = "******"
SEND_URL = "https://smssh.253.com/msg/sms/v2/tpl/send"

def assemble_template_params():
    """
    构建模板参数
    """
    list_data = []

    map1 = {"param1": "张1", "param2": "张2"}
    map2 = {"param1": "李1", "param2": "李2"}

    list_data.append(map1)
    list_data.append(map2)

    return list_data

def make_signature(md5_password, timestamp, nonce):
    """
    生成签名
    """
    str_data = generate_str(md5_password, timestamp, nonce)
    signature = hmac.new(md5_password.encode('utf-8'), str_data.encode('utf-8'), hashlib.sha256).hexdigest()
    return signature

def generate_str(md5_password, timestamp, nonce):
    """
    拼接签名字符串
    """
    array = [md5_password, timestamp, nonce]
    array.sort()
    return ''.join(array)

def send_sms_by_post(path, post_content, x_qa_hmac_signature):
    """
    发送 HTTP POST 请求
    """
    headers = {
        "Content-Type": "application/json; charset=UTF-8",
        "X-QA-Hmac-Signature": x_qa_hmac_signature
    }

    response = requests.post(path, data=post_content.encode('utf-8'), headers=headers)
    if response.status_code != 200:
        raise Exception(f"HTTP 请求失败，状态码：{response.status_code}")
    return response.text

def main():
    try:
        timestamp = str(int(time.time()))
        nonce = str(uuid.uuid4()).replace("-", "")

        # 构建模板参数
        template_params = assemble_template_params()
        template_param_json = json.dumps(template_params, ensure_ascii=False)

        # 构建请求参数
        request_map = {
            "account": ACCOUNT,
            "timestamp": timestamp,
            "nonce": nonce,
            "phoneNumbers": "15200000000,15100000000",
            "templateId": "1021143438",
            "templateParamJson": template_param_json,
            "signature": "【222】",
            "report": "true",
            "callbackUrl": "",
            "uid": "test_001",
            "extend": "01"
        }

        json_body = json.dumps(request_map, ensure_ascii=False)

        # 生成签名
        md5_password = hashlib.md5(PASSWORD.encode('utf-8')).hexdigest()
        signature = make_signature(md5_password, timestamp, nonce)

        # 发送请求
        response = send_sms_by_post(SEND_URL, json_body, signature)
        print("响应结果：" + response)

    except Exception as e:
        print(e)

if __name__ == "__main__":
    main()

PHP

复制成功⧉
<?php

// 账号信息（建议后续通过配置或环境变量注入）
const ACCOUNT  = 'M122343';
const PASSWORD = '******';
const SEND_URL = 'https://smssh.253.com/msg/sms/v2/tpl/send';

try {
    $timestamp = (string) time();
    $nonce     = generateNonce();

    // 构建模板参数
    $templateParams   = assembleTemplateParams();
    $templateParamJson = json_encode($templateParams, JSON_UNESCAPED_UNICODE);

    // 构建请求参数
    $requestMap = [
        'account'           => ACCOUNT,
        'timestamp'         => $timestamp,
        'nonce'             => $nonce,
        'phoneNumbers'      => '15200000000,15100000000',
        'templateId'        => '1021143438',
        'templateParamJson' => $templateParamJson,
        'signature'         => '【222】',
        'report'            => 'true',
        'callbackUrl'       => '',
        'uid'               => 'test_001',
        'extend'            => '01',
    ];

    $jsonBody = json_encode($requestMap, JSON_UNESCAPED_UNICODE);

    // 生成签名
    $md5Password = md5(PASSWORD);
    $signature   = makeSignature($md5Password, $timestamp, $nonce);

    // 发送请求
    $response = sendSmsByPost(SEND_URL, $jsonBody, $signature);
    echo "响应结果：{$response}\n";

} catch (Exception $e) {
    echo $e->getMessage() . "\n";
}

function assembleTemplateParams(): array
{
    return [
        ['param1' => '张1', 'param2' => '张2'],
        ['param1' => '李1', 'param2' => '李2'],
    ];
}

function sendSmsByPost(string $path, string $postContent, string $xQAHmacSignature): string
{
    $ch = curl_init($path);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $postContent,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT        => 10,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json; charset=UTF-8',
            'X-QA-Hmac-Signature: ' . $xQAHmacSignature,
        ],
    ]);

    $response = curl_exec($ch);
    if ($response === false) {
        $err = curl_error($ch);
        curl_close($ch);
        throw new Exception("cURL 请求失败：{$err}");
    }

    $httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("HTTP 请求失败，状态码：{$httpCode}");
    }

    return (string) $response;
}

function makeSignature(string $md5Password, string $timestamp, string $nonce): string
{
    $str = generateStr($md5Password, $timestamp, $nonce);
    return hash_hmac('sha256', preg_replace('/\s+/', '', $str), $md5Password);
}

function generateStr(string $md5Password, string $timestamp, string $nonce): string
{
    $array = [$md5Password, $timestamp, $nonce];
    sort($array, SORT_STRING);
    return implode('', $array);
}

function generateNonce(): string
{
    return bin2hex(random_bytes(16));
}

C#

复制成功⧉
using System;
using System.Collections.Generic;
using System.Globalization;
using System.IO;
using System.Linq;
using System.Net;
using System.Security.Cryptography;
using System.Text;
using System.Web.Script.Serialization;

namespace SmsClientDemo
{
    class Program
    {
        // 账号信息（建议后续通过配置或环境变量注入）
        private const string ACCOUNT = "M122343";
        private const string PASSWORD = "******";
        private const string SEND_URL = "https://smssh.253.com/msg/sms/v2/tpl/send";

        static void Main(string[] args)
        {
            try
            {
                string timestamp = ((DateTimeOffset)DateTime.Now).ToUnixTimeSeconds().ToString();
                string nonce = Guid.NewGuid().ToString("N");

                // 构建模板参数
                var templateParams = AssembleTemplateParams();
                var jss = new JavaScriptSerializer();
                string templateParamJson = jss.Serialize(templateParams);

                // 构建请求参数
                var requestMap = new Dictionary<string, object>
                {
                    { "account", ACCOUNT },
                    { "timestamp", timestamp },
                    { "nonce", nonce },
                    { "phoneNumbers", "15200000000,15100000000" },
                    { "templateId", "1021143438" },
                    { "templateParamJson", templateParamJson },
                    { "signature", "【222】" },
                    { "report", true },
                    { "callbackUrl", "" },
                    { "uid", "test_001" },
                    { "extend", "01" }
                };

                string jsonBody = jss.Serialize(requestMap);

                // 生成签名
                string md5Password = ComputeMD5(PASSWORD);
                string signature = MakeSignature(md5Password, timestamp, nonce);

                // 发送请求
                string response = SendSmsByPost(SEND_URL, jsonBody, signature);
                Console.WriteLine("响应结果：" + response);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.StackTrace);
            }
        }

        private static List<Dictionary<string, string>> AssembleTemplateParams()
        {
            var list = new List<Dictionary<string, string>>();

            var map1 = new Dictionary<string, string>
            {
                { "param1", "张1" },
                { "param2", "张2" }
            };

            var map2 = new Dictionary<string, string>
            {
                { "param1", "李1" },
                { "param2", "李2" }
            };

            list.Add(map1);
            list.Add(map2);

            return list;
        }

        private static string ComputeMD5(string input)
        {
            using (var md5 = MD5.Create())
            {
                byte[] inputBytes = Encoding.UTF8.GetBytes(input);
                byte[] hashBytes = md5.ComputeHash(inputBytes);

                StringBuilder sb = new StringBuilder();
                foreach (byte b in hashBytes)
                {
                    sb.Append(b.ToString("x2"));
                }
                return sb.ToString();
            }
        }

        private static string MakeSignature(string md5Password, string timestamp, string nonce)
        {
            string str = GenerateStr(md5Password, timestamp, nonce);
            return ComputeHmacSha256Hash(str, md5Password);
        }

        private static string GenerateStr(string md5Password, string timestamp, string nonce)
        {
            string[] array = { md5Password, timestamp, nonce };
            Array.Sort(array);
            return string.Concat(array);
        }

        private static string ComputeHmacSha256Hash(string input, string key)
        {
            using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(key)))
            {
                byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(input));
                StringBuilder sb = new StringBuilder();
                foreach (byte b in hashBytes)
                {
                    sb.Append(b.ToString("x2"));
                }
                return sb.ToString();
            }
        }

        private static string SendSmsByPost(string path, string postContent, string xQAHmacSignature)
        {
            var request = (HttpWebRequest)WebRequest.Create(path);
            request.Method = "POST";
            request.ContentType = "application/json; charset=UTF-8";
            request.Headers.Add("X-QA-Hmac-Signature", xQAHmacSignature);
            request.Timeout = 10000;
            request.ReadWriteTimeout = 10000;

            byte[] byteArray = Encoding.UTF8.GetBytes(postContent);
            request.ContentLength = byteArray.Length;

            using (Stream dataStream = request.GetRequestStream())
            {
                dataStream.Write(byteArray, 0, byteArray.Length);
            }

            using (var response = (HttpWebResponse)request.GetResponse())
            {
                if (response.StatusCode != HttpStatusCode.OK)
                {
                    throw new Exception($"HTTP 请求失败，状态码：{(int)response.StatusCode}");
                }

                using (var reader = new StreamReader(response.GetResponseStream(), Encoding.UTF8))
                {
                    return reader.ReadToEnd();
                }
            }
        }
    }
}

提交响应码说明