tencentcloud_sms/api/send_sms/
action.rs

1use crate::SmsClient;
2use crate::SmsResult;
3use crate::api::send_sms::request::SendSmsRequest;
4use crate::api::send_sms::response::SendStatus;
5
6impl SmsClient {
7    /// 发送短信
8    ///
9    /// # 参数
10    /// - `request`: 发送短信请求
11    ///
12    /// # 返回
13    /// 成功时返回每个号码的发送状态列表
14    ///
15    /// # 错误
16    /// - `InvalidParameter`: 参数错误（手机号格式、模板ID等）
17    /// - `RateLimited`: 触发频率限制
18    /// - `InsufficientBalance`: 余额不足
19    /// - `PartialFailure`: 部分号码发送失败
20    pub async fn send_sms(&self, request: SendSmsRequest) -> SmsResult<Vec<SendStatus>> {
21        self.execute(request).await
22    }
23
24    /// 快捷发送短信(无模板参数)
25    ///
26    /// 这是一个便捷方法,适用于不需要模板参数的简单短信发送场景。
27    ///
28    /// # 参数
29    /// - `app_id`: SMS 应用 ID (如 "1400123456")
30    /// - `phone_numbers`: 手机号列表,支持国内和国际号码
31    /// - `template_id`: 短信模板 ID
32    /// - `sign_name`: 短信签名名称
33    ///
34    /// # 示例
35    /// ```no_run
36    /// # use tencentcloud_sms::{SmsClient, Credential, ClientConfig};
37    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
38    /// # let client = SmsClient::new(
39    /// #     Credential::long_term("secret_id", "secret_key"),
40    /// #     ClientConfig::default()
41    /// # )?;
42    /// let results = client.send_simple_sms(
43    ///     "1400123456",
44    ///     &["13800000000", "13900000000"],
45    ///     "123456",
46    ///     "公司名称",
47    /// ).await?;
48    ///
49    /// for status in results {
50    ///     if status.is_success() {
51    ///         println!("✓ {} 发送成功", status.phone_number);
52    ///     }
53    /// }
54    /// # Ok(())
55    /// # }
56    /// ```
57    pub async fn send_simple_sms(
58        &self,
59        app_id: impl Into<String>,
60        phone_numbers: &[impl AsRef<str>],
61        template_id: impl Into<String>,
62        sign_name: impl Into<String>,
63    ) -> SmsResult<Vec<SendStatus>> {
64        let request = SendSmsRequest::builder()
65            .phone_number_set(
66                phone_numbers
67                    .iter()
68                    .map(|s| s.as_ref().to_string())
69                    .collect(),
70            )
71            .sms_sdk_app_id(app_id)
72            .template_id(template_id)
73            .sign_name(sign_name)
74            .build();
75
76        self.send_sms(request).await
77    }
78
79    /// 快捷发送带模板参数的短信
80    ///
81    /// 这是一个便捷方法,适用于需要填充模板参数的短信发送场景。
82    ///
83    /// # 参数
84    /// - `app_id`: SMS 应用 ID (如 "1400123456")
85    /// - `phone_numbers`: 手机号列表
86    /// - `template_id`: 短信模板 ID
87    /// - `sign_name`: 短信签名名称
88    /// - `template_params`: 模板参数列表,按模板中的占位符顺序填充
89    ///
90    /// # 示例
91    /// ```no_run
92    /// # use tencentcloud_sms::{SmsClient, Credential, ClientConfig};
93    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
94    /// # let client = SmsClient::new(
95    /// #     Credential::long_term("secret_id", "secret_key"),
96    /// #     ClientConfig::default()
97    /// # )?;
98    /// // 假设模板内容为: "您的验证码是{1},请在{2}分钟内完成验证"
99    /// let results = client.send_template_sms(
100    ///     "1400123456",
101    ///     &["13800000000"],
102    ///     "123456",
103    ///     "公司名称",
104    ///     &["888888", "5"],  // 验证码和有效期
105    /// ).await?;
106    /// # Ok(())
107    /// # }
108    /// ```
109    pub async fn send_template_sms(
110        &self,
111        app_id: impl Into<String>,
112        phone_numbers: &[impl AsRef<str>],
113        template_id: impl Into<String>,
114        sign_name: impl Into<String>,
115        template_params: &[impl AsRef<str>],
116    ) -> SmsResult<Vec<SendStatus>> {
117        let request = SendSmsRequest::builder()
118            .phone_number_set(
119                phone_numbers
120                    .iter()
121                    .map(|s| s.as_ref().to_string())
122                    .collect(),
123            )
124            .sms_sdk_app_id(app_id)
125            .template_id(template_id)
126            .sign_name(sign_name)
127            .template_param_set(
128                template_params
129                    .iter()
130                    .map(|s| s.as_ref().to_string())
131                    .collect(),
132            )
133            .build();
134
135        self.send_sms(request).await
136    }
137
138    /// 发送单条短信(最简化版本)
139    ///
140    /// 这是最简化的快捷方法,用于向单个手机号发送不含模板参数的短信。
141    ///
142    /// # 参数
143    /// - `app_id`: SMS 应用 ID
144    /// - `phone_number`: 单个手机号
145    /// - `template_id`: 短信模板 ID
146    /// - `sign_name`: 短信签名名称
147    ///
148    /// # 返回
149    /// 返回该手机号的发送状态
150    ///
151    /// # 示例
152    /// ```no_run
153    /// # use tencentcloud_sms::{SmsClient, Credential, ClientConfig};
154    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
155    /// # let client = SmsClient::new(
156    /// #     Credential::long_term("secret_id", "secret_key"),
157    /// #     ClientConfig::default()
158    /// # )?;
159    /// let status = client.send_single_sms(
160    ///     "1400123456",
161    ///     "13800000000",
162    ///     "123456",
163    ///     "公司名称",
164    /// ).await?;
165    ///
166    /// if status.is_success() {
167    ///     println!("短信发送成功!");
168    /// }
169    /// # Ok(())
170    /// # }
171    /// ```
172    pub async fn send_single_sms(
173        &self,
174        app_id: impl Into<String>,
175        phone_number: impl AsRef<str>,
176        template_id: impl Into<String>,
177        sign_name: impl Into<String>,
178    ) -> SmsResult<SendStatus> {
179        let results = self
180            .send_simple_sms(app_id, &[phone_number], template_id, sign_name)
181            .await?;
182
183        // 单条发送应该返回一个结果
184        results.into_iter().next().ok_or_else(|| {
185            crate::SmsError::UnexpectedResponse("发送单条短信时 API 返回空结果".to_string())
186        })
187    }
188
189    /// 发送单条带模板参数的短信
190    ///
191    /// # 参数
192    /// - `app_id`: SMS 应用 ID
193    /// - `phone_number`: 单个手机号
194    /// - `template_id`: 短信模板 ID
195    /// - `sign_name`: 短信签名名称
196    /// - `template_params`: 模板参数列表
197    ///
198    /// # 返回
199    /// 返回该手机号的发送状态
200    ///
201    /// # 示例
202    /// ```no_run
203    /// # use tencentcloud_sms::{SmsClient, Credential, ClientConfig};
204    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
205    /// # let client = SmsClient::new(
206    /// #     Credential::long_term("secret_id", "secret_key"),
207    /// #     ClientConfig::default()
208    /// # )?;
209    /// let status = client.send_single_template_sms(
210    ///     "1400123456",
211    ///     "13800000000",
212    ///     "123456",
213    ///     "公司名称",
214    ///     &["888888", "5"],
215    /// ).await?;
216    /// # Ok(())
217    /// # }
218    /// ```
219    pub async fn send_single_template_sms(
220        &self,
221        app_id: impl Into<String>,
222        phone_number: impl AsRef<str>,
223        template_id: impl Into<String>,
224        sign_name: impl Into<String>,
225        template_params: &[impl AsRef<str>],
226    ) -> SmsResult<SendStatus> {
227        let results = self
228            .send_template_sms(
229                app_id,
230                &[phone_number],
231                template_id,
232                sign_name,
233                template_params,
234            )
235            .await?;
236
237        // 单条发送应该返回一个结果
238        results.into_iter().next().ok_or_else(|| {
239            crate::SmsError::UnexpectedResponse(
240                "发送单条短信（带模板参数）时 API 返回空结果".to_string(),
241            )
242        })
243    }
244}
tencentcloud_sms/api/send_sms/action.rs

tencentcloud_sms/api/send_sms/
action.rs
