PHP使用SUBMAIL API发送短信完整示例

沈知远

发布时间：2026-10-13| 2人浏览过

原创

本文介绍如何使用 PHP 调用赛邮（SUBMAIL）短信平台 API 发送通知类短信。核心步骤包括构建请求参数、计算 MD5 数字签名以通过安全验证、封装 JSON 格式的模板数据，并利用 HTTP 客户端发起 POST 请求。文中提供了完整的可运行代码片段，适用于需要集成短信验证码或业务通知的场景。

短信通知接口调用原理

赛邮（SUBMAIL）的短信服务主要依赖于 RESTful API 接口进行通信。为了确保请求的安全性与合法性，API 要求客户端在发送请求前，必须按照特定规则对参数进行排序并生成签名（Signature）。服务端收到请求后，会重新计算签名并与请求中的 signature 字段比对，一致则允许下发短信。

官方接口文档与详细信息请访问：https://www.mysubmail.com/documents

环境准备

在开始代码编写前，请确保满足以下条件：

账号信息：已在 SUBMAIL 注册账号，并获取对应的 App ID 和 App Key。
短信模板：在控制台中已创建并通过审核的短信模板，获取 Project ID（模板ID）。
依赖库：PHP 环境需安装 Guzzle HTTP Client 或类似的 HTTP 客户端库以简化请求处理。

第1步：配置基础参数与接口地址

首先需要定义请求的基础变量，包括接收短信的手机号、应用凭证以及模板 ID。接口地址通常固定为 https://api-v4.mysubmail.com/sms/xsend（具体请以官方最新文档为准）。

第2步：构建签名验证逻辑

SUBMAIL 采用 MD5 签名机制。为了保证签名一致，必须将除 sign_type 和 sign_version 外的所有参数按键名 ASCII 码升序排列拼接字符串，并与 App ID 和 App Key 组合后计算 MD5 值。

以下是结合签名生成的完整 PHP 实现代码：

$url = 'https://api-v4.mysubmail.com/sms/xsend';//接口地址
$appId = 'your_app_id';//APPID，请替换为实际值
$appkey = 'your_app_key';//APPKEY，请替换为实际值
$phone = '13800138000';//发送手机号，请替换为实际值
$project = 'your_project_id';//模板ID，请替换为实际值

// 1. 构建基本参数数组
$data = [
    'appid' => $appId,
    'to' => $phone,
    'timestamp' => time(),
    'sign_type' => 'md5',
    'sign_version' => 2,
    'project' => $project
];

// 2. 键名排序，确保签名一致性
ksort($data);

// 3. 生成签名字符串：appid + appkey + query_string + appid + appkey
$signatureStr = $appId . $appkey . http_build_query($data) . $appId . $appkey;
$data['signature'] = md5($signatureStr);//添加数字签名到请求数据中

// 4. 设置模板变量
$vars = [
    'code' => '123456',//示例：验证码内容，可根据实际需求修改
];
$data['vars'] = json_encode($vars); // 注意：部分版本可能直接传数组，请参照文档调整

// 5. 发起HTTP请求
$client = new Client();
$response = $client->createRequest()
    ->setMethod('POST')
    ->setUrl($url)
    ->setData($data)
    ->setHeaders([
        'Content-Type'=>'application/json',
    ])
    ->setFormat(Client::FORMAT_JSON) //指定提交的数据格式为JSON
    ->send();

// 6. 处理响应
if ($response->getStatusCode() == 200) {
    $result = json_decode($response->getContent(), true);
    if ($result['status'] === 'success') {
        echo '短信发送成功';
    } else {
        echo '短信发送失败: ' . $result['msg'];
    }
} else {
    echo 'HTTP请求错误: ' . $response->getStatusCode();
}

完成判断

当代码执行后，若 $response 返回的状态码为 200 且业务状态（如 status 字段）显示 success，即表示短信已成功提交至运营商网络。此时指定的手机号应能收到由对应模板下发的短信内容。

排错与建议

签名错误：最常见的错误是 signature 不匹配。请检查 appid 和 appkey 是否正确，以及参数排序是否严格按照键名 ASCII 升序排列。特别注意 json_encode 输出的 JSON 字符串是否包含不可见字符。
模板未启用：如果提示模板不存在或未启用，请登录 SUBMAIL 控制台检查该 Project ID 对应的模板是否已通过审核并处于启用状态。
频率限制：避免短时间内向同一手机号发送大量短信，以免触发平台的防骚扰风控机制导致发送失败。