一括 MMS API

本ドキュメントでは、PaaSoo の一括 MMS API を使用して、1 回のリクエストで 1 ～ 5000 個の番号へ同時に MMS を送信する方法について説明します。MMS 機能の有効化が必要な場合や、その他の地域での MMS 要件がある場合は、速やかにアカウントマネージャーにご連絡いただくか、support@paasoo.com までご要望をお送りください。

1. 呼び出し方法

呼び出し方法

HTTP Method：POST
Content-Type：application/x-www-form-urlencoded
API エンドポイント：https://api.paasoo.com/batch_mms
リクエストパラメータのエンコード：特殊文字は URL エンコードを行ってください。
セキュリティ：HTTPS プロトコルの使用を推奨します。また、正しい key と secret を付与する必要があります。
一括送信数：1 回のリクエストで 1 ～ 5000 通の MMS を一括送信できます。

2. リクエストのサンプル

以下は cURL を例とし、POST + application/x-www-form-urlencoded 方式での呼び出し方法を示しています：

cURL
curl -X POST "https://api.paasoo.com/batch_mms" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=API_KEY&secret=API_SECRET&from=TEST&to=819011111111,819022222222&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 個の携帯電話番号をサポートします。複数の番号は半角カンマ (,) で区切ります。	819011111111,819022222222
text	string	はい	MMS のテキスト本文。画像（attachment）と組み合わせて使用できます。	This is test MMS from TEST
subject	string	いいえ	MMS の件名。通常は 20 文字以内です（詳細はゲートウェイの制限に従います）。一部のキャリア/端末ではタイトルバーに表示される場合があります。	text
attachment	string	はい	MMS に添付する画像ファイルの URL。PaaSoo サーバーに保存されたリンクを使用することをお勧めします。サイズ制限は通常 300KB 以下です。より大きな画像を送信する必要がある場合は、PaaSoo に連絡して対応する通信ゲートウェイと価格をご相談ください。	`https://example.com/example.jpg`

4. レスポンスパラメータの説明

4.1 レスポンスフィールドの説明

パラメータ	型	説明	サンプル
status	integer	PaaSoo クラウド通信プラットフォームに送信された際のレスポンスステータスコード。 API ステータスコード一覧： 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	宛先番号。国番号+携帯電話番号の形式。	819011111111
messageid	string	MMS メッセージの一意の識別子。	015bd4-d6dfa7-58w
status	integer	PaaSoo クラウド通信プラットフォームに送信された際の単一メッセージのステータスコード。 API ステータスコード一覧： 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

本 API はデフォルトで非常に高い送信弾力性を提供します。呼び出し時にエラーコード status=10 を受信した場合、業務の取り決めに従ってアカウントにカスタムレート制限が有効になっていることを示します。制限のしきい値を調整する必要がある場合は、アカウントマネージャーまたは PaaSoo テクニカルサポートチーム（support@paasoo.com）までご連絡ください。

4.2 成功レスポンスのサンプル

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

4.3 失敗レスポンスのサンプル

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

5. コードサンプル

以下は、主要なプログラミング言語で国際一括 MMS 送信 API を統合するためのシンプルなコードサンプルです。

Python
Node.js
PHP
Java
Go

import requests

# API エンドポイント
url = "https://api.paasoo.com/batch_mms"

# フォームデータ
payload = {
    "key": "API_KEY",                                 # あなたの API Key に置き換えてください
    "secret": "API_SECRET",                           # あなたの API Secret に置き換えてください
    "from": "TEST",                                   # 送信元 ID (Sender ID)
    "to": "819011111111,819022222222",                # 宛先番号、カンマ区切り
    "subject": "text",                                # MMS の件名
    "attachment": "https://example.com/example.jpg",  # 画像ファイルの URL
    "text": "これは TEST からのテスト MMS です"            # MMS 本文
}

# リクエストヘッダー
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("一括 MMS の送信に成功しました。batchid:", data.get("batchid"))
    else:
        print(f"一括 MMS の送信に失敗しました。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.com/batch_mms';

// URL エンコードされたフォームデータを準備
const data = new URLSearchParams({
    key: 'API_KEY',                                 // あなたの API Key に置き換えてください
    secret: 'API_SECRET',                           // あなたの API Secret に置き換えてください
    from: 'TEST',                                   // 送信元 ID (Sender ID)
    to: '819011111111,819022222222',                 // 宛先番号、カンマ区切り
    subject: 'text',                                // MMS の件名
    attachment: 'https://example.com/example.jpg',  // 画像ファイルの URL
    text: 'これは TEST からのテスト MMS です'            // MMS 本文
});

// 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('一括 MMS の送信に成功しました。batchid:', result.batchid);
    } else {
        console.log('一括 MMS の送信に失敗しました。status:', result.status, 'message:', result.status_code);
    }
})
.catch((error) => {
    console.error('リクエストに失敗しました:', error.message || error);
});

<?php

// API エンドポイント
$url = "https://api.paasoo.com/batch_mms";

// リクエストパラメータ
$data = [
    "key" => "API_KEY",                                 // あなたの API Key に置き換えてください
    "secret" => "API_SECRET",                           // あなたの API Secret に置き換えてください
    "from" => "TEST",                                   // 送信元 ID (Sender ID)
    "to" => "819011111111,819022222222",                // 宛先番号、カンマ区切り
    "subject" => "text",                                // MMS の件名
    "attachment" => "https://example.com/example.jpg",  // 画像ファイルの URL
    "text" => "これは TEST からのテスト MMS です"            // MMS 本文
];

// 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 "一括 MMS の送信に成功しました。batchid: " . $result['batchid'] . "\n";
    } else {
        echo "一括 MMS の送信に失敗しました。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", "819011111111,819022222222")                 // 宛先番号、カンマ区切り
                .add("subject", "text")                                // MMS の件名
                .add("attachment", "https://example.com/example.jpg")  // 画像ファイルの URL
                .add("text", "これは TEST からのテスト MMS です")           // MMS 本文
                .build();

        // リクエストを構築
        Request request = new Request.Builder()
                .url("https://api.paasoo.com/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.com/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", "819011111111,819022222222")                 // 宛先番号
    data.Set("subject", "text")                                // MMS の件名
    data.Set("attachment", "https://example.com/example.jpg")  // 画像ファイルの URL
    data.Set("text", "これは TEST からのテスト MMS です")           // MMS 本文

    // 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("一括 MMS の送信に成功しました。batchid:", result["batchid"])
    } else {
        fmt.Printf("一括 MMS の送信に失敗しました。status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

6. ベストプラクティスと注意事項

番号数の制限：1 回のリクエストでサポートされる番号は 1 ～ 5000 個です。必ずこの範囲を遵守してください。さらに大規模なメッセージを送信する場合は、PaaSoo に解決策をご相談ください。
画像サイズの制御と価格に関する注意事項：通常は 300KB を超えないようにすることをお勧めします。一部の目的地では、画像サイズや形式に対して追加の要件や価格の違いがある場合があります。事前にご確認いただくか、PaaSoo にお問い合わせください。
コンテンツのコンプライアンス：国内および国際的な法規制を遵守し、違反するコンテンツ（ポルノ、ギャンブル、政治など）の送信は避けてください。
テストと検証：正式な大規模送信の前に、必ず小規模な範囲でテストを実施し、受信率、効果、端末の互換性、およびコスト状況を確認してください。
同時実行とレート制御：高並行処理や大規模なバッチで MMS を送信する必要がある場合は、送信速度が速すぎることによるキューの遅延やゲートウェイの輻輳を避けるため、事前に PaaSoo と調整を行ってください。
コールバックとステータスレポート：送信成功後、コールバック URL または PaaSoo 管理コンソールを通じてメッセージのステータスを確認できます。サーバーがコールバックを提供する場合は、セキュリティポリシー（署名または IP ホワイトリスト）を必ず確保してください。

7. 付録

カバレッジ（対応範囲）：MMS のカバレッジは SMS のカバレッジと異なる場合があり、一部の国や地域ではまだサポートされていないか、追加の承認が必要です。ターゲット国についてご不明な点がある場合は、アカウントマネージャーにご相談ください。
マルチメディアトランスコーディング：一部のキャリアや端末向けに、PaaSoo は到達率を向上させるために画像のトランスコーディングや圧縮処理を行う場合があります。
料金計算：MMS の料金は通常、キャリアへの送信が成功した時点で計算されますが、具体的な課金ルールは国や地域によって異なる場合があります。詳細については営業部門にご確認ください。
追加のサポート：受信効果、端末での表示、または送信の安定性について特別な要件がある場合は、PaaSoo チームにご連絡いただき、より詳細なサポートを受けてください。

テクニカルサポート

API 連携の過程で技術的な問題やビジネスに関する疑問が生じた場合は、いつでも当社の開発者サポートチーム（support@paasoo.com）までご連絡ください。誠心誠意、技術的なサポートを提供いたします。

1. 呼び出し方法​

2. リクエストのサンプル​

3. リクエストパラメータの説明​

4. レスポンスパラメータの説明​

4.1 レスポンスフィールドの説明​

4.2 成功レスポンスのサンプル​

4.3 失敗レスポンスのサンプル​

5. コードサンプル​

6. ベストプラクティスと注意事項​

7. 付録​