Batch MMS API

This document introduces how to use the PaaSoo Batch MMS API to send MMS messages to 1 - 5000 numbers simultaneously in a single request. If you need to enable the MMS feature or have MMS requirements for other regions, please contact your account manager promptly, or send your requirements to support@paasoo.com.

1. Invocation Method

Invocation Method

• HTTP Method: POST
• Content-Type: application/x-www-form-urlencoded
• API Endpoint: https://api.paasoo.com/batch_mms
• Request Parameter Encoding: Please URL-encode special characters.
• Security: It is recommended to use the HTTPS protocol, and include the correct key and secret.
• Batch Sending Limit: You can send 1 - 5000 MMS messages per request.

---

2. Request Example

The following is an example using cURL to demonstrate how to call the API via 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=12025550123,12025550124&subject=text&attachment=https%3A%2F%2Fexample.com%2Fexample.jpg&text=This+is+test+mms+from+TEST"

Note

Multiple numbers in the to parameter should be separated by commas (,).
The URL in attachment must be URL-encoded.
The text parameter should be appropriately escaped or URL-encoded (e.g., for spaces and symbols).

---

3. Request Parameters

Parameter	Type	Required	Description	Example
key	string	Yes	API Key (composed of 8 letters or numbers), used to uniquely identify your account. Can be obtained in the PaaSoo dashboard.	Abcdefgh
secret	string	Yes	API Secret (composed of 8 letters or numbers), used in conjunction with the key for authentication. Can be obtained in the PaaSoo dashboard.	Abc123EF
from	string	Yes	Sender display name or number (Sender ID). Customization is supported in some countries. If you need to use a specific Sender ID, please contact technical support.	TEST
to	string	Yes	Destination Number, in the format of country code + phone number (without leading 00 or +). Supports 1 - 5000 mobile numbers; Multiple numbers are separated by commas (,).	12025550123,12025550124
text	string	Yes	MMS text content, which can be used together with an image (attachment).	This is test MMS from TEST
subject	string	No	MMS subject, usually not exceeding 20 characters (depending on Carrier restrictions). Some Operators/devices may display it in the title bar.	text
attachment	string	Yes	The URL of the image file attached to the MMS. It is recommended to use the storage link on the PaaSoo server. The size limit is generally under 300KB. If you need to send larger images, please contact PaaSoo to negotiate suitable Carrier routes and Pricing.	https://example.com/example.jpg

---

4. Response Parameters

4.1 Response Fields

Parameter	Type	Description	Example
status	integer	Response status code submitted to the PaaSoo cloud communication platform. API status code list: 0 - success 2 - Missing parameters 3 - Invalid parameters 4 - Invalid credentials 5 - Unauthorized IP: IP Whitelist restriction 6 - Invalid phone number 7 - Invalid sender id 8 - Message bombing detected: Repeated requests within 3 seconds 9 - Quota exceeded: Insufficient Balance or credit limit 10 - Throttling error: Rate limit exceeded (Throttling) 11 - System error 13 - Invalid attachment file: Invalid or inaccessible attachment 14 - Nb of messages per request should be between 1 and 5000: Number limit exceeded 18 - Invalid subject: Invalid subject or exceeds limit	0
status_code	string	Status description.	Invalid credentials
batchid	string	The unique identifier for this batch request.	a0018f-e4bf51-e000
data	array	Sending details for each number.	[...]

Fields in the data array

Field	Type	Description	Example
to	string	Destination Number, country code + phone number format.	12025550123
messageid	string	Message ID, the unique identifier for the MMS message.	015bd4-d6dfa7-58w
status	integer	Single message status code submitted to the PaaSoo cloud communication platform. API status code list: 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	Single message status description.	Missing parameters

By default, this API provides highly elastic sending capabilities. If you receive the error code status=10 during invocation, it means your account has triggered custom Throttling based on your business agreement. To adjust the Throttling threshold, please contact your account manager or the PaaSoo technical support team (support@paasoo.com).

4.2 Success Response Example

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

4.3 Failure Response Example

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

---

5. Code Examples

Below are simple code examples showing how to integrate the Batch MMS API in several popular programming languages.

Python

import requests

# API Endpoint
url = "https://api.paasoo.com/batch_mms"

# Form data
payload = {
    "key": "API_KEY",                                 # Replace with your API Key
    "secret": "API_SECRET",                           # Replace with your API Secret
    "from": "TEST",                                   # Sender ID
    "to": "12025550123,12025550124",                  # Destination Numbers, separated by commas
    "subject": "text",                                # MMS subject
    "attachment": "https://example.com/example.jpg",  # Image file URL
    "text": "This is a test MMS from TEST"            # MMS content
}

# Request Headers
headers = {
    "Content-Type": "application/x-www-form-urlencoded"
}

try:
    # Send HTTP POST request
    response = requests.post(url, data=payload, headers=headers)
    response.raise_for_status()
    
    # Parse and print JSON response
    data = response.json()
    if data.get("status") == 0:
        print("Batch MMS sent successfully, batchid:", data.get("batchid"))
    else:
        print(f"Failed to send Batch MMS, status: {data.get('status')}, message: {data.get('status_code')}")

except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Node.js

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

// API Endpoint
const url = 'https://api.paasoo.com/batch_mms';

// Prepare URL-encoded form data
const data = new URLSearchParams({
    key: 'API_KEY',                                 // Replace with your API Key
    secret: 'API_SECRET',                           // Replace with your API Secret
    from: 'TEST',                                   // Sender ID
    to: '12025550123,12025550124',                  // Destination Numbers, separated by commas
    subject: 'text',                                // MMS subject
    attachment: 'https://example.com/example.jpg',  // Image file URL
    text: 'This is a test MMS from TEST'            // MMS content
});

// Send HTTP POST request
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('Batch MMS sent successfully, batchid:', result.batchid);
    } else {
        console.log('Failed to send Batch MMS, status:', result.status, 'message:', result.status_code);
    }
})
.catch((error) => {
    console.error('Request failed:', error.message || error);
});

PHP

<?php

// API Endpoint
$url = "https://api.paasoo.com/batch_mms";

// Request parameters
$data = [
    "key" => "API_KEY",                                 // Replace with your API Key
    "secret" => "API_SECRET",                           // Replace with your API Secret
    "from" => "TEST",                                   // Sender ID
    "to" => "12025550123,12025550124",                  // Destination Numbers, separated by commas
    "subject" => "text",                                // MMS subject
    "attachment" => "https://example.com/example.jpg",  // Image file URL
    "text" => "This is a test MMS from TEST"            // MMS content
];

// Initialize cURL session
$ch = curl_init($url);

// Set cURL options (POST and 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"
]);

// Execute request
$response = curl_exec($ch);

if($e = curl_error($ch)) {
    echo "Request failed: " . $e;
} else {
    $result = json_decode($response, true);
    if (isset($result['status']) && $result['status'] === 0) {
        echo "Batch MMS sent successfully, batchid: " . $result['batchid'] . "\n";
    } else {
        echo "Failed to send Batch MMS, status: " . $result['status'] . ", message: " . $result['status_code'] . "\n";
    }
}

// Close cURL session
curl_close($ch);
?>

Java

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

// Ensure OkHttp dependency is added to your pom.xml or build.gradle
public class BulkMmsApiExample {
    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient();

        // Build x-www-form-urlencoded request body
        RequestBody formBody = new FormBody.Builder()
                .add("key", "API_KEY")                                 // Replace with your API Key
                .add("secret", "API_SECRET")                           // Replace with your API Secret
                .add("from", "TEST")                                   // Sender ID
                .add("to", "12025550123,12025550124")                  // Destination Numbers, separated by commas
                .add("subject", "text")                                // MMS subject
                .add("attachment", "https://example.com/example.jpg")  // Image file URL
                .add("text", "This is a test MMS from TEST")           // MMS content
                .build();

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

        // Execute request
        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                System.out.println("Response: " + response.body().string());
            } else {
                System.out.println("Request failed, status code: " + response.code());
            }
        } catch (IOException e) {
            System.err.println("Request failed: " + e.getMessage());
        }
    }
}

Go

package main

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

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

    // Prepare form data
    data := url.Values{}
    data.Set("key", "API_KEY")                                 // Replace with your API Key
    data.Set("secret", "API_SECRET")                           // Replace with your API Secret
    data.Set("from", "TEST")                                   // Sender ID
    data.Set("to", "12025550123,12025550124")                  // Destination Numbers
    data.Set("subject", "text")                                // MMS subject
    data.Set("attachment", "https://example.com/example.jpg")  // Image file URL
    data.Set("text", "This is a test MMS from TEST")           // MMS content

    // Send HTTP POST request
    req, err := http.NewRequest("POST", apiURL, strings.NewReader(data.Encode()))
    if err != nil {
        fmt.Println("Error creating request:", 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("Request failed:", err)
        return
    }
    defer resp.Body.Close()

    // Read response body
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Error reading response:", err)
        return
    }

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

    // Check status (Note: Go parses JSON numbers as float64 by default)
    if status, ok := result["status"].(float64); ok && status == 0 {
        fmt.Println("Batch MMS sent successfully, batchid:", result["batchid"])
    } else {
        fmt.Printf("Failed to send Batch MMS, status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

---

6. Best Practices and Precautions

1. Number Limit: Each request supports 1 - 5000 numbers. Please ensure you stay within this range. If you need to send messages on a larger scale, please contact PaaSoo to negotiate a solution.
2. Image Size Control and Pricing: It is generally not recommended to exceed 300KB. Some destinations may have additional requirements or Pricing differences based on image size and format. Please understand these in advance or consult PaaSoo.
3. Content Compliance: Comply with local and international laws and Operator policies. Avoid sending prohibited content (e.g., adult content, gambling, politics).
4. Testing and Verification: Before formal large-scale sending, be sure to conduct small-scale testing to check Delivery Rates, effectiveness, device compatibility, and costs.
5. Concurrency and Rate Limits: When you need to send Batch MMS messages with high concurrency, please coordinate with PaaSoo in advance to avoid queue delays or Carrier route congestion caused by excessive sending rates.
6. Callbacks and Status Reports: After successful sending, you can check the message status via the Callback / Webhook URL or in the PaaSoo dashboard; if your server provides a Callback, ensure security policies (Signature or IP Whitelist) are in place.

---

7. Appendix

• Coverage: MMS coverage may differ from SMS coverage. Some countries or regions are not yet supported or require additional approval. If you have questions about destination countries, please consult your account manager.
• Multimedia Transcoding: For some Operators or devices, PaaSoo may transcode or compress images to improve the Delivery Rate.
• Billing Calculation: MMS Billing is usually based on successful submission to the Carrier, but specific Billing rules may vary by country or region. Please confirm with the commercial department.
• Additional Support: If you have special requirements for reception effectiveness, device display, or sending stability, you can communicate with the PaaSoo team for more detailed support.

Support

If you encounter any technical issues or have business inquiries during the API integration, please do not hesitate to contact our Support team at support@paasoo.com. We are always here to assist you.