批量彩信 API

本文档介绍如何使用 PaaSoo 批量彩信（MMS）接口，以一次请求向 1 - 5000 个号码同时发送彩信。如果您需要开通彩信功能或有其它地区的彩信需求，请及时联系您的客户经理，或将需求发送至 support@paasoo.com。

1. 调用方式

调用方式

HTTP Method：POST
Content-Type：application/x-www-form-urlencoded
API Endpoint：https://api.paasoo.cn/batch_mms
请求参数编码：请对特殊字符进行 URL 编码。
安全性：建议使用 HTTPS 协议，并携带正确的 key 与 secret。
批量发送数量：每次请求可批量发送 1 - 5000 条彩信。

2. 请求示例

以下以 cURL 为例，展示如何通过 POST + application/x-www-form-urlencoded 的方式调用：

cURL
curl -X POST "https://api.paasoo.cn/batch_mms" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=API_KEY&secret=API_SECRET&from=TEST&to=8618911111111,8618922222222&subject=text&attachment=https%3A%2F%2Fexample.com%2Fexample.jpg&text=This+is+test+mms+from+TEST"

说明

to 参数中多个号码使用英文逗号 , 分隔。
attachment 中的 URL 需要进行 URL 编码。
text 建议做适当的转义或 URL 编码（如空格、符号）。

3. 请求参数说明

参数	类型	必填	描述	示例
key	string	是	API Key（字母或数字构成，共 8 位），用于唯一标识您的账户。可在PaaSoo 客户端后台获取。	Abcdefgh
secret	string	是	API Secret（字母或数字构成，共 8 位），与 `key` 配合使用以进行身份验证。可在PaaSoo 客户端后台获取。	Abc123EF
from	string	是	发件人显示名称或号码（Sender ID），部分国家支持自定义。如需使用特定 Sender ID，请联系技术支持。	TEST
to	string	是	接收目标手机号，格式为`国家区号 + 手机号码`（不含前导 00 或 +）。支持 1 - 5000 个手机号码；多个号码之间用英文逗号(,)分隔。	8618911111111,8618922222222
text	string	是	彩信文字内容，可与图片（attachment）搭配使用。	This is test MMS from TEST
subject	string	否	彩信主题，通常不超过 20 个字符（具体依照通道限制）。部分运营商/终端可能会显示在标题栏。	text
attachment	string	是	彩信中附带的图片文件地址建议使用 PaaSoo 服务器上存储的链接，大小限制一般为 300KB 以下。若需发送更大图片，请联系 PaaSoo 协商适配的通信通道与定价。	`https://example.com/example.jpg`

4. 响应参数说明

4.1 响应字段说明

参数	类型	描述	示例
status	integer	提交至 PaaSoo 云通讯平台的响应状态码。接口状态码列表： 0 - success：提交成功 2 - Missing parameters：缺少必要参数 3 - Invalid parameters：参数格式错误 4 - Invalid credentials：key 或 secret 错误 5 - Unauthorized IP：IP 限制 6 - Invalid phone number：号码格式错误 7 - Invalid sender id：from 参数格式错误 8 - Message bombing detected：3秒内重复请求 9 - Quota exceeded：欠费或信用额度不足 10 - Throttling error：超过限速 11 - System error：系统错误 13 - Invalid attachment file：附件不合法或无法访问 14 - Nb of messages per request should be between 1 and 5000：号码数量超限 18 - Invalid subject：主题不合法或超出限制	0
status_code	string	状态描述。	Invalid credentials
batchid	string	本次批量请求的唯一标识。	a0018f-e4bf51-e000
data	array	每个号码的发送详情。	[...]

data 数组中的字段

字段	类型	描述	示例
to	string	发送目标号码，国家区号+手机号格式。	8618911111111
messageid	string	彩信消息的唯一标识。	015bd4-d6dfa7-58w
status	integer	提交至 PaaSoo 云通讯平台的单条消息状态码。接口状态码列表： 0 - success：提交成功 2 - Missing parameters 3 - Invalid parameters 4 - Invalid credentials 5 - Unauthorized IP 6 - Invalid phone number 7 - Invalid sender id 8 - Message bombing detected 9 - Quota exceeded 10 - Throttling error 11 - System error 13 - Invalid attachment file 18 - Invalid subject	0
status_code	string	单条消息状态描述。	Missing parameters

本接口默认提供极高的发送弹性。若您在调用时收到错误码status=10，说明您的账户已根据业务约定开启了自定义速率限制。如需调整限速阈值，请联系您的客户经理或 PaaSoo 技术支持团队（support@paasoo.com）。

4.2 成功响应示例

{
    "status": 0,
    "status_code": "success",
    "batchid": "a0018f-e4bf51-e000",
    "data": [
        {
            "status": 0,
            "to": "8618911111111",
            "messageid": "00018f-e4bf51-e002"
         },
        {
            "status": 0,
            "to": "8618922222222",
            "messageid": "00018f-e4bf51-e003"
        }
    ]
}

4.3 失败响应示例

{
    "status": 4,
    "status_code": "Invalid credentials."
}

5. 代码示例

以下是在几种流行的编程语言中集成批量发送国际彩信 API 的简单代码示例。

Python
Node.js
PHP
Java
Go

import requests

# API 接口端点
url = "https://api.paasoo.cn/batch_mms"

# 表单数据
payload = {
    "key": "API_KEY",                                 # 替换为您的 API Key
    "secret": "API_SECRET",                           # 替换为您的 API Secret
    "from": "TEST",                                   # 发送者 ID (Sender ID)
    "to": "8618911111111,8618922222222",              # 目标号码，以逗号分隔
    "subject": "text",                                # 彩信主题
    "attachment": "https://example.com/example.jpg",  # 图片文件的 URL
    "text": "这是一条来自 TEST 的测试彩信"                # 彩信内容
}

# 请求头
headers = {
    "Content-Type": "application/x-www-form-urlencoded"
}

try:
    # 发送 HTTP POST 请求
    response = requests.post(url, data=payload, headers=headers)
    response.raise_for_status()
    
    # 解析并打印 JSON 响应
    data = response.json()
    if data.get("status") == 0:
        print("群发彩信发送成功，batchid:", data.get("batchid"))
    else:
        print(f"群发彩信发送失败，status: {data.get('status')}, message: {data.get('status_code')}")

except requests.exceptions.RequestException as e:
    print(f"请求失败: {e}")

const axios = require('axios'); // 运行: npm install axios

// API 接口端点
const url = 'https://api.paasoo.cn/batch_mms';

// 准备 URL 编码的表单数据
const data = new URLSearchParams({
    key: 'API_KEY',                                 // 替换为您的 API Key
    secret: 'API_SECRET',                           // 替换为您的 API Secret
    from: 'TEST',                                   // 发送者 ID (Sender ID)
    to: '8618911111111,8618922222222',              // 目标号码，以逗号分隔
    subject: 'text',                                // 彩信主题
    attachment: 'https://example.com/example.jpg',  // 图片文件的 URL
    text: '这是一条来自 TEST 的测试彩信'                // 彩信内容
});

// 发送 HTTP POST 请求
axios.post(url, data.toString(), {
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    }
})
.then((response) => {
    const result = response.data;
    if (result.status === 0) {
        console.log('群发彩信发送成功，batchid:', result.batchid);
    } else {
        console.log('群发彩信发送失败，status:', result.status, 'message:', result.status_code);
    }
})
.catch((error) => {
    console.error('请求失败:', error.message || error);
});

<?php

// API 接口端点
$url = "https://api.paasoo.cn/batch_mms";

// 请求参数
$data = [
    "key" => "API_KEY",                                 // 替换为您的 API Key
    "secret" => "API_SECRET",                           // 替换为您的 API Secret
    "from" => "TEST",                                   // 发送者 ID (Sender ID)
    "to" => "8618911111111,8618922222222",              // 目标号码，以逗号分隔
    "subject" => "text",                                // 彩信主题
    "attachment" => "https://example.com/example.jpg",  // 图片文件的 URL
    "text" => "这是一条来自 TEST 的测试彩信"                // 彩信内容
];

// 初始化 cURL 会话
$ch = curl_init($url);

// 设置 cURL 选项（POST 和 x-www-form-urlencoded）
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/x-www-form-urlencoded"
]);

// 执行请求
$response = curl_exec($ch);

if($e = curl_error($ch)) {
    echo "请求失败: " . $e;
} else {
    $result = json_decode($response, true);
    if (isset($result['status']) && $result['status'] === 0) {
        echo "群发彩信发送成功，batchid: " . $result['batchid'] . "\n";
    } else {
        echo "群发彩信发送失败，status: " . $result['status'] . ", message: " . $result['status_code'] . "\n";
    }
}

// 关闭 cURL 会话
curl_close($ch);
?>

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.FormBody;
import okhttp3.Response;
import java.io.IOException;

// 确保在您的 pom.xml 或 build.gradle 中添加了 OkHttp 依赖
public class BulkMmsApiExample {
    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient();

        // 构建 x-www-form-urlencoded 请求体
        RequestBody formBody = new FormBody.Builder()
                .add("key", "API_KEY")                                 // 替换为您的 API Key
                .add("secret", "API_SECRET")                           // 替换为您的 API Secret
                .add("from", "TEST")                                   // 发送者 ID (Sender ID)
                .add("to", "8618911111111,8618922222222")              // 目标号码，以逗号分隔
                .add("subject", "text")                                // 彩信主题
                .add("attachment", "https://example.com/example.jpg")  // 图片文件的 URL
                .add("text", "这是一条来自 TEST 的测试彩信")               // 彩信内容
                .build();

        // 构建请求
        Request request = new Request.Builder()
                .url("https://api.paasoo.cn/batch_mms")
                .post(formBody)
                .addHeader("Content-Type", "application/x-www-form-urlencoded")
                .build();

        // 执行请求
        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                System.out.println("响应: " + response.body().string());
            } else {
                System.out.println("请求失败，状态码: " + response.code());
            }
        } catch (IOException e) {
            System.err.println("请求失败: " + e.getMessage());
        }
    }
}

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
    "strings"
)

func main() {
    apiURL := "https://api.paasoo.cn/batch_mms"

    // 准备表单数据
    data := url.Values{}
    data.Set("key", "API_KEY")                                 // 替换为您的 API Key
    data.Set("secret", "API_SECRET")                           // 替换为您的 API Secret
    data.Set("from", "TEST")                                   // 发送者 ID (Sender ID)
    data.Set("to", "8618911111111,8618922222222")              // 目标号码
    data.Set("subject", "text")                                // 彩信主题
    data.Set("attachment", "https://example.com/example.jpg")  // 图片文件的 URL
    data.Set("text", "这是一条来自 TEST 的测试彩信")               // 彩信内容

    // 发送 HTTP POST 请求
    req, err := http.NewRequest("POST", apiURL, strings.NewReader(data.Encode()))
    if err != nil {
        fmt.Println("创建请求出错:", err)
        return
    }
    req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("请求失败:", err)
        return
    }
    defer resp.Body.Close()

    // 读取响应体
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("读取响应出错:", err)
        return
    }

    // 解析 JSON
    var result map[string]interface{}
    if err := json.Unmarshal(body, &result); err != nil {
        fmt.Println("解析 JSON 出错:", err)
        return
    }

    // 检查状态（注意：Go 默认将 JSON 数字解析为 float64）
    if status, ok := result["status"].(float64); ok && status == 0 {
        fmt.Println("群发彩信发送成功，batchid:", result["batchid"])
    } else {
        fmt.Printf("群发彩信发送失败，status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

6. 最佳实践与注意事项

号码数量限制：每次请求支持 1 - 5000 个号码，请务必遵循此范围。若要发送更大规模的消息，请联系 PaaSoo 协商解决方案。
图片大小控制与定价提醒：一般不建议超过 300KB。部分目的地可能对图片大小和格式有额外要求或定价区别，请事先了解或咨询 PaaSoo。
内容合规：遵守当地和国际法律法规，避免发送违规内容（色情、博彩、政治等）。
测试与验证：在正式大规模发送前，务必先做小范围测试，查看接收率、效果、终端兼容性及费用情况。
并发与速率控制：需要高并发、大批次发彩信时，请提前与 PaaSoo 协调，避免因发送速率过快造成队列延迟或通道拥塞。
回调与状态报告：发送成功后可通过回调 URL 或在 PaaSoo 后台查看消息状态；若服务器提供回调，请确保安全策略（签名或 IP 白名单）。

7. 附录

覆盖范围：彩信覆盖可能与短信覆盖不同，部分国家或地区暂未支持或需额外审批。对目标国家有疑问时，请咨询客户经理。
多媒体转码：对于部分运营商或终端，PaaSoo 可能对图片进行转码或压缩处理，以提高送达率。
费用计算：彩信费用通常按照成功向运营商提交时计费，但具体计费规则可能因国家或地区有所不同，请与商务部门确认。
额外支持：若对接收效果、终端展示或发送稳定性有特殊需求，可与 PaaSoo 团队沟通以获得更详细支持。

技术支持

如在 API 对接过程中遇到任何技术问题或业务疑问，欢迎随时联系我们的开发者支持团队：support@paasoo.com。我们将竭诚为您提供技术协助。

1. 调用方式​

2. 请求示例​

3. 请求参数说明​

4. 响应参数说明​

4.1 响应字段说明​

4.2 成功响应示例​

4.3 失败响应示例​

5. 代码示例​

6. 最佳实践与注意事项​

7. 附录​