SMS Gateway API Reference

Integrate SMS messaging into your applications two ways — a modern JSON API with per-recipient personalised messages and structured responses, or the classic HTTP GET/POST API. Built for transactional alerts, OTP delivery, bulk campaigns, and notifications.

📡 API Endpoint URLs

Four redundant hosts are provided for each API. Hosts 1 and 2 are recommended for production — configure your integration to fall back to the alternatives if the primary is unavailable.

🔤 SMS Encoding Types

The type parameter controls character encoding. Use type 1 for Latin-script languages and type 2 for Chinese, Japanese, Arabic, and other non-ASCII scripts.

✉️ Send SMS

Pick the API that fits your integration. The JSON API sends up to 50 recipients — each with its own personalised message — in a single request and returns structured per-recipient results. The classic API uses form-encoded GET/POST with one shared message per call.

POST /isms_send_json.php HTTP/1.1
Host: www.isms.com.my
Content-Type: application/json

{
  "un":         "myusername",
  "pwd":        "mypassword",
  "type":       "1",
  "sendid":     "MyCompany",
  "agreedterm": "YES",
  "messages": [
    { "dstno": "6016xxxxxxx", "msg": "Hi Ali, your order #123 is ready for pickup" },
    { "dstno": "6019xxxxxxx", "msg": "Hi Siti, your appointment is confirmed at 3pm" },
    { "dstno": "6017xxxxxxx", "msg": "Hi Kumar, payment of RM150 received. Thank you" }
  ]
}

<?php
$payload = [
    "un"         => "myusername",
    "pwd"        => "mypassword",
    "type"       => "1",            // 1 = ASCII, 2 = Unicode
    "sendid"     => "MyCompany",   // Max 11 chars, optional
    "agreedterm" => "YES",
    "messages"   => [
        ["dstno" => "6016xxxxxxx", "msg" => "Hi Ali, your order #123 is ready"],
        ["dstno" => "6019xxxxxxx", "msg" => "Hi Siti, your appointment is at 3pm"]
    ]
];

$ch = curl_init("https://www.isms.com.my/isms_send_json.php");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$result   = curl_exec($ch);
curl_close($ch);

$response = json_decode($result, true);
echo $response["message"];               // e.g. "2000 = SUCCESS"

foreach ($response["results"] as $r) {   // per-recipient outcome
    echo $r["dstno"] . " => " . $r["status"];
}
?>

GET /isms_send_all_id.php HTTP/1.1
Host: www.isms.com.my

?un=myusername
&pwd=mypassword
&dstno=601X-XXXXXXX
&msg=Hello%20World
&type=1
&sendid=MyCompany
&agreedterm=YES

<?php
$params = [
    "un"         => "myusername",
    "pwd"        => "mypassword",
    "dstno"      => "601X-XXXXXXX",  // International format, no +
    "msg"        => "Hello World! Your OTP is 123456.",
    "type"       => "1",            // 1 = ASCII, 2 = Unicode
    "sendid"     => "MyCompany",   // Max 11 chars, optional
    "agreedterm" => "YES"
];

$ch = curl_init("https://www.isms.com.my/isms_send_all_id.php");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));

$result = curl_exec($ch);
curl_close($ch);

// Result format: "2000 = SUCCESS:1143007207" or "-1001" for errors
echo $result;
?>

<?php
// Separate multiple recipients with semicolons — all receive the same message
$params = [
    "un"         => "myusername",
    "pwd"        => "mypassword",
    "dstno"      => "601X-XXXXXXX;601X-XXXXXXX;601X-XXXXXXX",
    "msg"        => "Your appointment reminder for tomorrow at 9am.",
    "type"       => "1",
    "sendid"     => "ClinicABC",
    "agreedterm" => "YES"
];

$ch = curl_init("https://www.isms.com.my/isms_send_all_id.php");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));

$result = curl_exec($ch);
curl_close($ch);
echo $result;
?>

🏷️ Personalisation Tokens

Embed these tokens in any message body. Each is replaced with the matching field from your iSMS contact list (matched by phone number). If no contact record is found, the token is replaced with the recipient's phone number. Supported by both the JSON and classic APIs.

💰 Check Balance — JSON POST

Retrieve the remaining SMS credit balance for a prepaid account.

Request Parameters

Sample Request

POST /isms_balance_json.php HTTP/1.1
Host: www.isms.com.my
Content-Type: application/json

{
  "un":  "myusername",
  "pwd": "mypassword"
}

Sample Responses

✅ API Response Codes

Every API request returns a response code. 2000 means the message was accepted and queued for delivery. All other codes indicate an error.

📬 Delivery Status Callback (HTTP Push)

iSMS supports server-side delivery status notifications via HTTP Push. When a telco delivery update is received, the iSMS platform makes an HTTPS GET request to your callback URL with status parameters as query strings.

Callback URL Format

Example Callback

Delivery Status Values

PHP Callback Handler Example

<?php
// iSMS Delivery Status Callback Handler
$msisdn    = $_GET['msisdn']    ?? '';    // Destination number
$trx_id    = $_GET['trx_id']    ?? '';    // Transaction ID
$dn_status = $_GET['dn_status'] ?? '';    // DELIVERED / UNDELIVERED / PENDING

if ($trx_id && $dn_status) {
    // Log to database
    $query = "UPDATE sms_log SET status='%s', updated_at=NOW() 
               WHERE trx_id='%s'";
    // Execute $query with $dn_status and $trx_id ...
    
    // Handle delivery outcomes
    if ($dn_status === 'DELIVERED') {
        // Mark as delivered in your system
    } elseif ($dn_status === 'UNDELIVERED') {
        // Alert or retry logic
    }
}

// Return 200 OK to acknowledge receipt
http_response_code(200);
echo "OK";
?>

🔄 Migrating from the Classic API

The JSON API keeps the same account credentials, sender IDs, credit billing, IP whitelisting, personalisation tokens, and response codes. Only the request and response shape change.