## 一、选择 SMS API


相比自建短信网关或使用 Twilio 等海外平台，该 SMS API 对中国企业开发者有明显优势：
- **国内 + 国际一站式覆盖**：通过 `sms/unionsend`单接口自动按国家路由
- **REST API 设计简洁**：标准 HTTP POST，Java 无需官方 SDK 也可轻松接入
- **覆盖全球 200+ 国家和地区**，送达率业界领先
- **支持 normal / MD5 / SHA1 / SHA256 多种认证方式**，安全灵活


----
 
## 二、前期准备


**1. 注册账号并创建应用**
注册账号，进入控制台「应用集成」→「国际短信」，创建应用，获取：
- `AppID`：应用唯一标识
- `AppKey`：应用密钥（请妥善保管，切勿提交至代码仓库）

**2. 确认账户余额**
国际短信按条计费，发送前请在控制台确认余额充足。


----
 
## 三、环境依赖


**JDK 版本要求**：JDK 1.8 及以上
使用 **OkHttp3** 作为 HTTP 客户端，**Gson** 解析 JSON 响应。
**Maven 依赖（pom.xml）：**
```xml
```<dependencies>
 
 <dependency>
 <groupId>com.squareup.okhttp3</groupId>
 <artifactId>okhttp</artifactId>
 <version>4.12.0</version>
 </dependency>
 
 <dependency>
 <groupId>com.google.code.gson</groupId>
 <artifactId>gson</artifactId>
 <version>2.10.1</version>
 </dependency>
</dependencies>```

**Gradle 依赖（build.gradle）：**
```groovy
```implementation 'com.squareup.okhttp3:okhttp:4.12.0'
implementation 'com.google.code.gson:gson:2.10.1'```

----
 
## 四、核心 API 说明

- **接口地址**：`https://api-v4.mysubmail.com/internationalsms/send`
- **请求方式**：HTTP POST
- **Content-Type**：`application/x-www-form-urlencoded`

**主要请求参数：**
- `appid`（必需）：国际短信应用 AppID
- `signature`（必需）：`normal` 模式填 AppKey 明文；`md5` 模式填签名字符串
- `to`（必需）：收件人手机号，**必须携带国际区号**，格式如 `+1xxxxxxxxxx`（美国）、`+44xxxxxxxxxx`（英国）、`+81xxxxxxxxxx`（日本）
- `content`（必需）：短信正文
- `sign_type`（可选）：认证类型，`normal`（测试用）或 `md5`（生产推荐）


----
 
## 五、完整 Java 示例代码


### 方式一：normal 明文认证（快速测试）

```Java
import okhttp3.*;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.IOException;
public class SubmailSmsSender {
 // 从环境变量读取，避免硬编码密钥
 private static final String APPID = System.getenv("SUBMAIL_APPID");
 private static final String APPKEY = System.getenv("SUBMAIL_APPKEY");
 private static final String API_URL =
 "https://api-v4.mysubmail.com/internationalsms/send";
 private final OkHttpClient client = new OkHttpClient();
 /**
 * 发送国际短信（normal 明文认证模式）
 *
 * @param to 收件人号码，需带国际区号，如 +1xxxxxxxxxx
 * @param content 短信正文
 * @return API 响应的 JsonObject
 */
 public JsonObject sendSms(String to, String content) throws IOException {
 // 构建请求体
 RequestBody body = new FormBody.Builder()
 .add("appid", APPID)
 .add("signature", APPKEY) // normal 模式直接传 AppKey
 .add("to", to)
 .add("content", content)
 .add("sign_type", "normal")
 .build();
 Request request = new Request.Builder()
 .url(API_URL)
 .post(body)
 .build();
 // 发送请求并解析响应
 try (Response response = client.newCall(request).execute()) {
 if (!response.isSuccessful()) {
 throw new IOException("HTTP 请求失败，状态码：" + response.code());
 }
 String responseBody = response.body().string();
 return JsonParser.parseString(responseBody).getAsJsonObject();
 }
 }
 /**
 * 统一处理 API 响应
 */
 public static void handleResponse(JsonObject result) {
 String status = result.get("status").getAsString();
 if ("success".equals(status)) {
 System.out.println("✅ 发送成功！");
 System.out.println(" send_id: " + result.get("send_id").getAsString());
 System.out.println(" 消耗额度: " + result.get("fee").getAsInt());
 System.out.println(" 剩余额度: " + result.get("sms_credits").getAsInt());
 } else {
 System.out.println("❌ 发送失败！");
 System.out.println(" 错误码: " + result.get("code").getAsString());
 System.out.println(" 原因: " + result.get("msg").getAsString());
 }
 }
 public static void main(String[] args) throws IOException {
 SubmailSmsSender sender = new SubmailSmsSender();
 // 发送给美国号码
 JsonObject result = sender.sendSms(
 "+11234567890",
 "Your verification code is 8866. Valid for 5 minutes. --SUBMAIL"
 );
 handleResponse(result);
 }
}
```

----
### 方式二：MD5 签名认证（生产环境推荐）

```java
import okhttp3.*;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.IOException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Map;
import java.util.TreeMap;
public class SubmailSmsMd5Sender {
 private static final String APPID = System.getenv("SUBMAIL_APPID");
 private static final String APPKEY = System.getenv("SUBMAIL_APPKEY");
 private static final String API_URL =
 "https://api-v4.mysubmail.com/internationalsms/send";
 private final OkHttpClient client = new OkHttpClient();
 /**
 * 构建 SUBMAIL MD5 数字签名
 * 规则：appid + appkey + 排序后参数字符串 + appid + appkey，取 MD5
 */
 private String buildMd5Signature(Map<String, String> params) {
 // 使用 TreeMap 自动按 key 排序
 TreeMap<String, String> sorted = new TreeMap<>(params);
 sorted.remove("sign_type");
 StringBuilder paramStr = new StringBuilder();
 for (Map.Entry<String, String> entry : sorted.entrySet()) {
 if (paramStr.length() > 0) paramStr.append("&");
 paramStr.append(entry.getKey()).append("=").append(entry.getValue());
 }
 // 拼接签名原文
 String raw = APPID + APPKEY + paramStr + APPID + APPKEY;
 // MD5 加密
 try {
 MessageDigest md = MessageDigest.getInstance("MD5");
 byte[] hash = md.digest(raw.getBytes("UTF-8"));
 StringBuilder sb = new StringBuilder();
 for (byte b : hash) {
 sb.append(String.format("%02x", b));
 }
 return sb.toString();
 } catch (Exception e) {
 throw new RuntimeException("MD5 签名生成失败：" + e.getMessage());
 }
 }
 /**
 * 发送国际短信（MD5 签名认证模式）
 */
 public JsonObject sendSmsWithMd5(String to, String content) throws IOException {
 // 先组装参数（不含 sign_type 和 signature）
 Map<String, String> params = new TreeMap<>();
 params.put("appid", APPID);
 params.put("to", to);
 params.put("content", content);
 // 生成 MD5 签名
 String signature = buildMd5Signature(params);
 // 构建最终请求体
 FormBody.Builder formBuilder = new FormBody.Builder();
 for (Map.Entry<String, String> entry : params.entrySet()) {
 formBuilder.add(entry.getKey(), entry.getValue());
 }
 formBuilder.add("signature", signature);
 formBuilder.add("sign_type", "md5");
 Request request = new Request.Builder()
 .url(API_URL)
 .post(formBuilder.build())
 .build();
 try (Response response = client.newCall(request).execute()) {
 String responseBody = response.body().string();
 return JsonParser.parseString(responseBody).getAsJsonObject();
 }
 }
 public static void main(String[] args) throws IOException {
 SubmailSmsMd5Sender sender = new SubmailSmsMd5Sender();
 // 发送给英国号码
 JsonObject result = sender.sendSmsWithMd5(
 "+447911123456",
 "Hello! Your order #ORD20260323 has been shipped. --SUBMAIL"
 );
 System.out.println("API 响应：" + result.toString());
 }
}
```

----
### 方式三：使用模板发送（internationalsms/xsend）

如果你在 SUBMAIL 控制台预先创建了短信模板，可以使用 `xsend` 接口，通过变量动态替换模板内容，适合 OTP 验证码、订单通知等标准化场景：
```java
import okhttp3.*;
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.IOException;
import java.util.Map;
public class SubmailSmsTemplateSender {
 private static final String APPID = System.getenv("SUBMAIL_APPID");
 private static final String APPKEY = System.getenv("SUBMAIL_APPKEY");
 private static final String XSEND_URL =
 "https://api-v4.mysubmail.com/internationalsms/xsend";
 private final OkHttpClient client = new OkHttpClient();
 private final Gson gson = new Gson();
 /**
 * 使用模板发送国际短信
 *
 * @param to 收件人号码（带国际区号）
 * @param project 模板 ID（控制台中的 project 字段）
 * @param variables 模板变量，如 {"code": "8866", "minutes": "5"}
 */
 public JsonObject sendWithTemplate(String to, String project,
 Map<String, String> variables)
 throws IOException {
 // 将变量 Map 序列化为 JSON 字符串
 String varsJson = gson.toJson(variables);
 RequestBody body = new FormBody.Builder()
 .add("appid", APPID)
 .add("signature", APPKEY)
 .add("to", to)
 .add("project", project)
 .add("vars", varsJson)
 .add("sign_type", "normal")
 .build();
 Request request = new Request.Builder()
 .url(XSEND_URL)
 .post(body)
 .build();
 try (Response response = client.newCall(request).execute()) {
 String responseBody = response.body().string();
 return JsonParser.parseString(responseBody).getAsJsonObject();
 }
 }
 public static void main(String[] args) throws IOException {
 SubmailSmsTemplateSender sender = new SubmailSmsTemplateSender();
 // 模板内容示例：【SUBMAIL】你好 @var(name)，验证码 @var(code)，@var(minutes) 分钟有效
 Map<String, String> vars = Map.of(
 "name", "张三",
 "code", "9527",
 "minutes", "5"
 );
 JsonObject result = sender.sendWithTemplate(
 "+8613812345678", // 中国大陆号码
 "your_template_id",
 vars
 );
 System.out.println("API 响应：" + result);
 }
}
```
----
 
## 六、批量发送建议

需要向多个用户批量发送时，推荐以下方案：
**使用线程池实现异步并发发送：**
```java
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.List;
public class BulkSmsSender {
 // 线程池大小根据 SUBMAIL 套餐 QPS 限制调整
 private static final int THREAD_POOL_SIZE = 10;
 public void sendBulk(List<String> phoneNumbers, String content) {
 ExecutorService executor = Executors.newFixedThreadPool(THREAD_POOL_SIZE);
 SubmailSmsSender sender = new SubmailSmsSender();
 for (String phone : phoneNumbers) {
 executor.submit(() -> {
 try {
 var result = sender.sendSms(phone, content);
 SubmailSmsSender.handleResponse(result);
 } catch (Exception e) {
 System.err.println("❌ 发送失败 [" + phone + "]：" + e.getMessage());
 }
 });
 }
 executor.shutdown();
 }
}
```

**或使用 `internationalsms/batchsend` 接口**，支持单次请求发送最多 10,000 个号码，性能更佳，建议超过 100 条时优先使用。


----
 
## 七、错误处理与常见错误码

**成功响应示例：**
```json
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.List;
public class BulkSmsSender {
 // 线程池大小根据 SUBMAIL 套餐 QPS 限制调整
 private static final int THREAD_POOL_SIZE = 10;
 public void sendBulk(List<String> phoneNumbers, String content) {
 ExecutorService executor = Executors.newFixedThreadPool(THREAD_POOL_SIZE);
 SubmailSmsSender sender = new SubmailSmsSender();
 for (String phone : phoneNumbers) {
 executor.submit(() -> {
 try {
 var result = sender.sendSms(phone, content);
 SubmailSmsSender.handleResponse(result);
 } catch (Exception e) {
 System.err.println("❌ 发送失败 [" + phone + "]：" + e.getMessage());
 }
 });
 }
 executor.shutdown();
 }
}
```

**失败响应示例：**
```json
{
 "status": "error",
 "code": "103",
 "msg": "Unauthorized"
}
```

**常见错误码：**
- `103`：AppID 或 AppKey 错误 → 检查环境变量配置是否正确
- `104`：签名验证失败 → 检查 MD5 签名算法，注意参数排序和编码格式（UTF-8）
- `108`：短信额度不足 → 前往控制台充值
- `401`：收件人号码格式错误 → 国际号码必须以 `+` 开头加区号
- `402`：内容违规 → 检查短信正文是否含敏感词


----
 
## 八、安全建议

🔐 **绝对不要将 AppKey 硬编码在代码或 Git 仓库中**，推荐以下方案：
**Linux / macOS 环境变量：**
```bash
export SUBMAIL_APPID="your_appid"
export SUBMAIL_APPKEY="your_appkey"
```
**Spring Boot 项目（application.yml）：**
```yaml
submail:
 appid: ${SUBMAIL_APPID}
 appkey: ${SUBMAIL_APPKEY}
```
```java
@Value("${submail.appid}")
private String appId;
@Value("${submail.appkey}")
private String appKey;
```
**生产环境推荐方案：**
- **Docker / Kubernetes** → 通过 Secret 注入环境变量
- **阿里云** → 使用 KMS 密钥管理服务
- **AWS** → 使用 AWS Secrets Manager
- **本地开发** → 使用 `.env` 文件，并将其加入 `.gitignore`


----
 
## 九、小结

- **JDK 要求**：JDK 1.8 及以上
- **核心依赖**：OkHttp3 4.12.0 + Gson 2.10.1
- **发送接口**：`https://api-v4.mysubmail.com/internationalsms/send`
- **模板接口**：`https://api-v4.mysubmail.com/internationalsms/xsend`
- **号码格式**：必须带 `+` 国际区号
- **认证方式**：测试用 `normal`，生产用 `md5`


与 Python 版本相比，Java 接入 SUBMAIL SMS API 同样简单直接，借助 OkHttp3 和 Gson，整个核心发送逻辑不超过 50 行代码。从注册到发出第一条国际短信，**通常只需 30 分钟**。

----

相比自建短信网关或使用 Twilio 等海外平台，该 SMS API 对中国企业开发者有明显优势：

用 Java 调用 SMS API 发送国际短信

Java 接入 SUBMAIL SMS API 同样简单直接，借助 OkHttp3 和 Gson，整个核心发送逻辑不超过 50 行代码。从注册到发出第一条国际短信，通常只需 30 分钟

编程语言

开发工具

后端

中国企业开发者首选SMSAPI，支持全球200+国家短信发送，提供REST API和Java示例代码，覆盖国内国际双通道，送达率领先。支持normal/MD5/SHA多种认证，安全灵活，快速接入仅需30分钟。

国内短信特惠0.04元/条起，接入便捷，稳定可靠


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

用 Java 调用 SMS API 发送国际短信-腾讯云开发者社区-腾讯云

用 Java 调用 SMS API 发送国际短信

用 Java 调用 SMS API 发送国际短信

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐