MMS API

Through this API, you can send MMS (Multimedia Messaging Service) messages to mobile users in various countries/regions around the world, delivering a more visually impactful and interactive experience through images. If you need to enable the MMS feature or have MMS requirements for specific countries/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/mms
Request Parameter Encoding: Please URL-encode special characters.
Security: It is recommended to use the HTTPS protocol. You must include the correct key and secret for a successful API call.

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/mms" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=API_KEY&secret=API_SECRET&from=TEST&to=12025550123&subject=text&attachment=https%3A%2F%2Fexample.com%2Fexample.jpg&text=This+is+test+mms+from+TEST"

Note

The URL in attachment must be URL-encoded.
The text parameter also requires appropriate escaping or URL encoding (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 your account manager or technical support (support@paasoo.com).	TEST
to	string	Yes	Destination Number, in the format of `country code + phone number` (without leading 00 or +). For example, a US number is written as 12025550123.	12025550123
text	string	Yes	The text content of the MMS, which can be used together with an image (`attachment`).	This is test MMS from TEST
subject	string	No	The 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. Please use the storage link obtained after uploading to the PaaSoo server. Recommended size limit: Under 300KB.	`https://example.com/example.jpg`
requestId	string	No	A unique request ID used to identify this request for tracking and troubleshooting. To ensure idempotency, please use a different `requestId` for each request; If the same request ID is used within 60 seconds, it will be treated as the same request. The system will return the same response as the first request without duplicate charging or sending.	0432258a-ecc7-4628-9158-2b883fe65181

4. Response Parameters

Upon success, the API returns a status code of 0 along with the corresponding Message ID.
Upon failure, it returns the corresponding error status code and description.

4.1 Response Fields

Parameter	Type	Description	Example
messageid	string	Message ID, the unique identifier for each MMS record.	015bd4-d6dfa7-58w
status	string	Response status code returned by the PaaSoo cloud communication platform. Generally, "0" means success.	"0"
status_code	string	Status description, providing the reason for the error or detailed status.	Missing parameters

4.2 Success Response Example

{
    "status": "0",
    "messageid": "015bd4-d6dfa7-58w"
}

4.3 Failure Response Example

{
    "status": "2",
    "status_code": "Missing parameters."
}

5. API Status Codes

0 - success: Success
2 - Missing parameters: Required parameters are missing
3 - Invalid parameters: Parameter format error
4 - Invalid credentials: API Key or API Secret error
5 - Unauthorized IP: IP Whitelist restriction
6 - Invalid phone number: Number format error
7 - Invalid sender id: from parameter format error
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: System error
13 - Invalid attachment file: MMS attachment is invalid or inaccessible
18 - Invalid subject: Subject is invalid or exceeds limits

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

6. Code Examples

Below are simplified code examples showing how to integrate the "Send Single International MMS API" in several popular programming languages. Only the core instructions are kept to maintain clean code:

Python
Node.js
PHP
Java
Go

import requests

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

payload = {
    "key": "API_KEY",                                 # Replace with your API Key
    "secret": "API_SECRET",                           # Replace with your API Secret
    "from": "TEST",                                   # Sender ID
    "to": "12025550123",                              # Destination Number
    "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("MMS sent successfully, messageid:", data.get("messageid"))
    else:
        print(f"Failed to send MMS, status: {data.get('status')}, message: {data.get('status_code')}")

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

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

// API Endpoint
const url = 'https://api.paasoo.com/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',                              // Destination Number
    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('MMS sent successfully, messageid:', result.messageid);
    } else {
        console.log('Failed to send MMS, status:', result.status, 'message:', result.status_code);
    }
})
.catch((error) => {
    console.error('Request failed:', error.message || error);
});

<?php

// API Endpoint
$url = "https://api.paasoo.com/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",                              // Destination Number
    "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 "MMS sent successfully, messageid: " . $result['messageid'] . "\n";
    } else {
        echo "Failed to send MMS, status: " . $result['status'] . ", message: " . $result['status_code'] . "\n";
    }
}

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

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")                              // Destination Number
                .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/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());
        }
    }
}

package main

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

func main() {
    apiURL := "https://api.paasoo.com/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")                              // Destination Number
    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("MMS sent successfully, messageid:", result["messageid"])
    } else {
        fmt.Printf("Failed to send MMS, status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

7. Delivery Status Reports and Callbacks

A successful message submission does not guarantee that the end device has successfully received it. The PaaSoo backend will initiate an MMS request to the target Carrier and generate a status report after the message transmission is complete. You can check the specific MMS status, such as "Delivered" or "Failed" and the specific reasons, via a Callback URL or in the dashboard.

8. Best Practices and Precautions

Image Size Control and Pricing: Some countries or Operators have strict limits on MMS sizes, generally recommending under 300KB. Additionally, for some destinations, the sending price may vary depending on the image size. If you need to send larger media files, contact PaaSoo to see if there are specialized Carrier routes available.
Content Compliance and Review: MMS content must comply with local laws, regulations, and Operator policies. Avoid sending prohibited text or images (e.g., adult content, gambling, politics).
Testing and Verification: Before conducting large-scale sends, please perform small-scale testing to verify Delivery Rates, device compatibility with the MMS, and cost calculations.
Concurrency and Rate Limits: If you need to send a large volume of MMS messages quickly, please negotiate Carrier capacity and bandwidth with PaaSoo in advance to avoid route congestion caused by excessive speed.
Webhook Security: Verify Callback requests on your server side (via Signatures or IP Whitelist) to ensure that the received status reports come from a legitimate source.

9. FAQ

Can I send an MMS to multiple numbers in a single request?

Yes, we have a dedicated Batch MMS API for mass-sending scenarios. Please refer to the corresponding documentation.

What if the sent MMS subject is not visible on the handset?

Some mobile operating systems or Operators may not display the subject separately when showing an MMS. This depends on the specific device model and Operator capabilities.

Can I use my own server's image links as MMS attachments?

We recommend using media files uploaded to PaaSoo or reliable CDN links to ensure network accessibility and loading speed. If you have special requirements, please communicate with technical support.

If the MMS fails to send, how is it billed?

Billing is usually based on successful submission to the Carrier, rather than the final delivery status. However, specific details should be confirmed with our commercial department.

10. Appendix

Coverage: MMS coverage may differ from SMS coverage. If you have any questions or need to confirm supported destinations, please consult your account manager.
Multimedia Transcoding: When sending to certain Carriers, the PaaSoo platform may automatically compress or transcode attachments to improve the success rate.
Alternative Fallbacks: If you are concerned about poor Delivery Rates or media playback issues on certain devices, consider sending an SMS link alongside it, or monitor subsequent status reports to troubleshoot promptly.

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.

1. Invocation Method​

2. Request Example​

3. Request Parameters​

4. Response Parameters​

4.1 Response Fields​

4.2 Success Response Example​

4.3 Failure Response Example​

5. API Status Codes​

6. Code Examples​

7. Delivery Status Reports and Callbacks​

8. Best Practices and Precautions​

9. FAQ​

10. Appendix​