API
API
简体中文

发送短信

用于通过 API 向国际号码发送短信（如 otp 验证码，marketing 营销，notification 通知）。

📌 请求方式

  • URL: api.moymobile.com/sms
  • 协议: HTTP / HTTPS
  • Method: POST
  • 认证方式: Basic Auth（Base64 编码的账号信息）

📮 请求头（Headers）

Header 名称 类型 是否必填 描述
Authorization string ✅ 使用 Basic 认证方式, 格式为：Basic Base64(AccountID:ApiKey)
Content-Type string ✅ 固定为 application/json
Authorization 示例说明

假设：

  • AccountID: 1910159943521189888
  • ApiKey: 12f76074-f686-4b23-8b15-8714651b815c 拼接字符串为：
1910159943521189888:12f76074-f686-4b23-8b15-8714651b815c

Base64 编码后为：

MTkxMDE1OTk0MzUyMTE4OTg4ODoxMmY3NjA3NC1mNjg2LTRiMjMtOGIxNS04NzE0NjUxYjgxNWM=

最终请求头写为：

Authorization: Basic MTkxMDE1OTk0MzUyMTE4OTg4ODoxMmY3NjA3NC1mNjg2LTRiMjMtOGIxNS04NzE0NjUxYjgxNWM=

🧾 请求参数（Request Body）

参数名 类型 必填 说明
from string ✅ 发送方标识（Sender ID）
to 对象数组 ✅ 接收方列表，每一项包含手机号及可选变量
templateId string ✅ 模板 ID，用于发送模板短信
reference string ❌ 自定义参数，最大 400 字符，会原样返回在状态回执中

每个 to 项的结构：

字段名 类型 必填 说明
phoneNumber string ✅ 接收方手机号，E.164 格式（例如 +14155550000）
其他变量 string / number 可选 根据模板定义传入所需变量（例如 code）

例如如果模板是：
Your verification code is: ${code}
则必须在 to 中传入 code 变量。
如果模板中没有变量，则只需要传入 phoneNumber。

请求体示例
{
  "from": "0018667261852",
  "to": [
    {
      "phoneNumber": "+17783227779",
      "code": 2234
    }
  ],
  "reference": "reference",
  "templateId": "101"
}

📌 国际短信按提交计费。

📌 E.164 格式为 “+” + 国家码 + 手机号，例如 +14155550000。

📌 模板 ID 在控制台中分配，变量（例如 code）会自动替换。

📌 计费字符数在变量替换后统计： GSM 7bit 编码一条短信最多 160 字符，超出 160 则每条 153 字符拆分； Unicode 编码一条短信最多 70 字符，超出 70 则每条 67 字符拆分。

💻 Request Example

Java OkHttp 
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n" +
    "    \"from\": \"moy\",\n" +
    "    \"to\": [\n" +
    "        {\n" +
    "            \"phoneNumber\": \"+14155550000\",\n" +
    "            \"code\": 2234\n" +
    "        }\n" +
    "    ],\n" +
    "    \"reference\": \"reference\",\n" +
    "    \"templateId\": \"101\"\n" +
    "}");
Request request = new Request.Builder()
  .url("https://api.moymobile.com/sms")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Basic MTkxMDE1OTk0MzUyMTE4OTg4ODoxMmY3NjA3NC1mLTRiMjMtOGIxNS04NzE0NjUxYjgxNWM=")
  .build();
Response response = client.newCall(request).execute();

✅ 成功响应示例（200 OK）

{
  "code": 0,
  "message": "Success",
  "data": [
    {
      "messageId": "1933000268379787264",
      "accountId": "1910159943521189888",
      "to": "+14155550000",
      "from": "1",
      "status": "PENDING",
      "fee": 0.0051,
      "parts": 1,
      "submittedAt": "2025-06-12T03:15:52.047Z",
      "currency": "USD"
    }
  ]
}

📦 响应字段说明（data 数组）

字段名 类型 描述
messageId string 短信唯一 ID （全局唯一）
accountId string 账户 ID
to string 接收号码
from string 发送标识符
status string 当前状态，如 PENDING
fee number 短信费用，单位元
currency string 货币类型（如 USD）
parts number 分段数（长短信会被拆分）
submittedAt string 提交时间（ISO 8601 格式，yyyy-MM-dd'T'HH:mm:ss.SSS'Z'）

❌ 错误响应示例（认证失败）

{
  "code": 1001,
  "message": "缺少或无效的授权标头。",
  "data": null
}

📘 状态码说明

以下为业务层的状态码，返回在 JSON 响应体中。
在 HTTP 协议层仍然遵循标准状态码（如 200、400、401、500），
业务状态码应结合 HTTP 状态一并理解。

业务码 描述
0 请求处理成功
1001 缺少或无效的 Authorization 头
1002 无效的 Basic Authentication 格式
1003 缺少或无效的账户标识
1004 账户未激活
1005 请求 IP 地址未在白名单中，已被限制
1006 请求体为空或格式错误
1007 缺少必填参数
1008 messageType 参数无效
1009 手机号码格式错误（必须为 E.164 格式）
1010 当前国家/地区未配置计费信息
1011 账户余额不足
1012 模板不存在、未通过审核或已过期
1013 对于该手机号缺少必填变量
1000 其他未定义的服务器错误

ℹ️ 这些状态码在响应体中的 code 字段返回。
如果请求在 HTTP 层面正常，会返回 200 OK；若发生传输级别错误，则可能返回 4xx 或 5xx 的 HTTP 状态码。

大纲