调用SendSms接口发送短信-短信服务-阿里云

接口说明

本接口主要用于向单个手机号发送短信，也支持向多个手机号（单次最多支持 1000 个手机号）发送相同签名、相同模板变量的短信，群发存在一定延迟。如果您需要向多个手机号发送不同签名、不同模板变量的短信，请使用 SendBatchSms 接口（单次最多支持 100 个手机号）。

注意事项

国内短信服务超时时间建议设置为≥1S；发生超时失败的情况时，建议查看回执状态后再判断是否重试。超时和重试的相关设置，请参见超时机制、重试机制。
国内短信、国际短信及多媒体短信目前均不支持幂等的能力，请您做好幂等控制，防止因多次重试而导致的重复操作问题。
发送短信为计费接口，国内短信按照运营商回执状态计费，调用 SendSms 提交成功但运营商回执失败时不计费。计费详情请参见计费概述。

QPS 限制

本接口的单用户 QPS 限制为 5000/秒。超过限制，API 调用将会被限流，请合理使用。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

dysms:SendSms

get

*全部资源

*

无

请求参数

名称	类型	必填	描述	示例值
PhoneNumbers	string	是	接收短信的手机号码。手机号码格式：国内短信：+/+86/0086/86 或无任何前缀的手机号码，例如 1390000**。国际/港澳台消息：国际区号+号码，例如 852000012**。接收测试短信的手机号：必须先在控制台绑定测试手机号后才可以发送。说明支持向不同的手机号码发送短信，手机号码之间以半角逗号（,）分隔。上限为 1000 个手机号码。批量发送相对于单条发送，及时性稍有延迟。验证码类型的短信，建议单条发送。	1390000****
SignName	string	是	短信签名名称。您可以通过 QuerySmsSignList 接口查询当前账号已申请的签名或在短信服务控制台查看签名列表，必须使用审核通过的签名发送短信。说明 1、如果验证码签名和通用签名相同时，默认使用通用签名发送短信。 2、系统会根据您选择的签名执行短信发送任务。	阿里云
TemplateCode	string	是	短信模板 Code。您可以通过 QuerySmsTemplateList 接口查询当前账号已申请的模板或在短信服务控制台查看模板列表，必须使用已审核通过的模板 Code 发送短信。	SMS_15305****
TemplateParam	string	否	短信模板变量对应的实际值，请传入JSON 字符串。当您选择的模板内容含有变量时，此参数必填。参数个数应与模板内变量个数一致。说明如果 JSON 中需要带换行符，请参照标准的 JSON 协议处理。模板变量规范，请参见短信模板规范。	{"name":"张三","number":"1390000****"}
SmsUpExtendCode	string	否	上行短信扩展码。上行短信指发送给通信服务提供商的短信，用于定制某种服务、完成查询，或是办理某种业务等，需要收费，按运营商普通短信资费进行扣费。说明扩展码是生成签名时系统自动默认生成的，不支持自行传入。无特殊需要可忽略此字段。	90999
OutId	string	否	外部流水扩展字段。说明无特殊需要可忽略此字段。	abcdefgh

请求示例

服务地址 URL：dysmsapi.aliyuncs.com（中国站）
请求风格：RPC
请求方式：POST/GET （推荐使用 POST）
公共请求头： V3 版本请求体公共请求头
请求参数：见上方请求参数表格

SDK 示例

如果您需要了解如何使用 SDK，请参见首次调用 API。

// 构造请求对象
SendSmsRequest sendSmsRequest = new SendSmsRequest()
            .setPhoneNumbers("1390000****")
            .setSignName("阿里云")
            .setTemplateCode("SMS_15305****")
            // TemplateParam 为序列化后的 JSON 字符串。其中\"表示转义后的双引号。
            .setTemplateParam("{\"name\":\"张三\",\"number\":\"1390000****\"}"); 

// 发送 API 请求
SendSmsResponse sendSmsResponse = client.sendSms(sendSmsRequest);

您可以访问 OpenAPI 门户，查看各语言 SDK 请求完整示例。

自签名请求示例

推荐您通过 SDK 调用 API，SDK 已经封装了签名等机制。

POST /?PhoneNumbers=123****4567&SignName=阿里云短信测试&TemplateCode=SMS_154950909&TemplateParam={"code":"1234"} HTTP/1.1
Host: dysmsapi.aliyuncs.com
Authorization: ACS3-HMAC-SHA256 Credential=YourAccessKeyId,SignedHeaders=host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version,Signature=06563a9e1b43f5dfe96b81********ceab24a1d853912eee15083a6f0f3283c0
x-acs-action: SendSms
x-acs-version: 2017-05-25
x-acs-signature-nonce: d410180a5abf7f********74aca91fc0
x-acs-date: 2024-12-02T06:53:09Z
x-acs-content-sha256: e3b0c44298fc1c149afb********b92427ae41e4649b934ca495991b7852b855

自定义封装 API 调用签名机制，请参见 V3 版本签名机制示例。

返回参数

名称	类型	描述	示例值
	object	返回数据。
Code	string	请求状态码。返回 OK 代表请求成功。其他错误码，请参见 API 错误码。	OK
Message	string	状态码的描述。	OK
BizId	string	发送回执 ID。可根据发送回执 ID 在接口 QuerySendDetails 中查询具体的发送状态。	9006197469364984****
RequestId	string	请求 ID。	F655A8D5-B967-440B-8683-DAD6FF8DE990

示例

正常返回示例

JSON格式

{
  "Code": "OK",
  "Message": "OK",
  "BizId": "9006197469364984****",
  "RequestId": "F655A8D5-B967-440B-8683-DAD6FF8DE990"
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。