SMPP Server API

Overview

The SMSDESK SMPP Server allows external systems to connect and send/receive SMS messages using the industry-standard SMPP v3.4 protocol. This is ideal for:

• ERP systems with built-in SMPP support
• Legacy applications that only support SMPP
• Third-party software requiring SMPP connectivity
• Customers without direct MNO licenses

Key Features

Connection Details

Server Configuration

PDU Parameters

Authentication

SMPP authentication uses your SMSDESK API credentials:

Credentials

System ID: your-email@example.com
Password:  your-api-key (first 8 characters only)

Bind Process

1. Connect to server address on port 2775
2. Send BIND_TRANSMITTER, BIND_RECEIVER, or BIND_TRANSCEIVER PDU
3. Include your email as system_id
4. Include the first 8 characters of your API key as password
5. Server validates credentials and responds with BIND_RESP
6. Server retrieves your default channel for message routing

Bind Response Codes

Supported Operations

1. Send SMS (SUBMIT_SM)

Submit an SMS message for delivery to a mobile number.

PDU Structure

SUBMIT_SM PDU:
  service_type: ""
  source_addr_ton: 0 or 5 (alphanumeric)
  source_addr_npi: 0
  source_addr: "Any" (ignored - default channel used)
  dest_addr_ton: 1 (international)
  dest_addr_npi: 1 (ISDN)
  dest_addr: "264811234567" (without + prefix)
  esm_class: 0
  protocol_id: 0
  priority_flag: 0
  schedule_delivery_time: ""
  validity_period: ""
  registered_delivery: 0 or 1 (for delivery reports)
  replace_if_present_flag: 0
  data_coding: 0 (Latin1) or 8 (UCS2)
  sm_default_msg_id: 0
  sm_length: [message length]
  short_message: "Your message text"

Response

SUBMIT_SM_RESP PDU:
  command_status: 0x00000000 (success)
  message_id: "12345" (unique message ID)

2. Receive SMS (DELIVER_SM)

Receive incoming SMS messages from mobile users.

PDU Structure

DELIVER_SM PDU (from server):
  service_type: ""
  source_addr_ton: 0
  source_addr_npi: 0
  source_addr: "+264811234567" (sender's number)
  dest_addr_ton: 0
  dest_addr_npi: 0
  dest_addr: "YourChannel" (your shortcode/number)
  esm_class: 0
  protocol_id: 0
  priority_flag: 0
  schedule_delivery_time: ""
  validity_period: ""
  registered_delivery: 0
  replace_if_present_flag: 0
  data_coding: 0
  sm_default_msg_id: 0
  sm_length: [message length]
  short_message: "Incoming message text"

Response Required

DELIVER_SM_RESP PDU:
  command_status: 0x00000000 (success)

3. Enquire Link (ENQUIRE_LINK)

Keepalive mechanism to maintain connection.

ENQUIRE_LINK PDU → ENQUIRE_LINK_RESP

4. Unbind (UNBIND)

Gracefully close the SMPP session.

UNBIND PDU → UNBIND_RESP → Connection closed

Code Examples

Python (smpplib)

import smpplib.client

# Connect to SMPP server
client = smpplib.client.Client('{host}', 2775)

# Bind as transceiver
# Password = first 8 characters of your API key
client.connect()
client.bind_transceiver(
    system_id='your-email@example.com',
    password='rqym36t4'  # First 8 chars of API key
)

# Send SMS
# Note: source_addr is ignored, your default channel is used
client.send_message(
    source_addr='Any',  # Ignored - default channel used
    destination_addr='264811234567',  # No + prefix
    short_message=b'Hello from SMPP!'
)

print('✓ Message sent successfully!')

# Unbind and disconnect
client.unbind()
client.disconnect()

PHP (php-smpp)

<?php
require_once 'vendor/autoload.php';

use PhpSmpp\Transport\Socket;
use PhpSmpp\Client;
use PhpSmpp\SMPP;

// Create transport
$transport = new Socket(['sms.com.na'], 2775);
$transport->open();

// Create client
$smpp = new Client($transport);

// Bind with API key (first 8 characters)
$smpp->bindTransceiver(
    'your-email@example.com',
    'rqym36t4'  // First 8 chars of API key
);

// Send SMS (source is ignored, default channel used)
$smpp->sendSMS(
    'Any',  // Ignored - default channel used
    '264811234567',  // No + prefix
    'Hello from SMPP!',
    null,
    SMPP::DATA_CODING_DEFAULT
);

echo "✓ Message sent successfully!\n";

// Unbind
$smpp->close();
?>

Java (jSMPP)

import org.jsmpp.bean.*;
import org.jsmpp.session.SMPPSession;

public class SmppExample {
    public static void main(String[] args) throws Exception {
        SMPPSession session = new SMPPSession();
        
        // Connect and bind with API key (first 8 characters)
        session.connectAndBind(
            "{host}", 
            2775,
            new BindParameter(
                BindType.BIND_TRX,
                "your-email@example.com",
                "rqym36t4",  // First 8 chars of API key
                "SMSDESK",
                TypeOfNumber.UNKNOWN,
                NumberingPlanIndicator.UNKNOWN,
                null
            )
        );
        
        // Send SMS (source is ignored, default channel used)
        String messageId = session.submitShortMessage(
            "CMT",
            TypeOfNumber.UNKNOWN,
            NumberingPlanIndicator.UNKNOWN,
            "Any",  // Ignored - default channel used
            TypeOfNumber.INTERNATIONAL,
            NumberingPlanIndicator.ISDN,
            "264811234567",  // No + prefix
            new ESMClass(),
            (byte) 0,
            (byte) 1,
            null,
            null,
            new RegisteredDelivery(SMSCDeliveryReceipt.DEFAULT),
            (byte) 0,
            new GeneralDataCoding(Alphabet.ALPHA_DEFAULT),
            (byte) 0,
            "Hello from SMPP!".getBytes()
        );
        
        System.out.println("✓ Message sent! ID: " + messageId);
        
        // Unbind
        session.unbindAndClose();
    }
}

C# (.NET)

using JamaaTech.Smpp.Net.Client;
using JamaaTech.Smpp.Net.Lib;

class Program
{
    static void Main()
    {
        // Create client
        var client = new SmppClient();
        client.Name = "SMSDESK-Client";
        
        // Connect
        client.Start();
        
        // Bind with API key (first 8 characters)
        client.Bind(
            "{host}",
            2775,
            "your-email@example.com",
            "rqym36t4"  // First 8 chars of API key
        );
        
        // Send SMS (source is ignored, default channel used)
        var message = new TextMessage
        {
            DestinationAddress = "264811234567",  // No + prefix
            SourceAddress = "Any",  // Ignored - default channel used
            Text = "Hello from SMPP!",
            RegisterDeliveryNotification = false
        };
        
        client.SendMessage(message);
        
        Console.WriteLine("✓ Message sent successfully!");
        
        // Unbind
        client.Shutdown();
    }
}

Error Codes

The SMPP server returns standard SMPP v3.4 error codes. Common errors:

View Complete Error Code Reference

Best Practices

Connection Management

• Use TRANSCEIVER: Bind as TRANSCEIVER for both sending and receiving
• Implement Keepalive: Send ENQUIRE_LINK every 30-60 seconds
• Handle Reconnection: Automatically reconnect on connection loss
• Graceful Shutdown: Always send UNBIND before disconnecting

Message Handling

• Check Response Codes: Always verify SUBMIT_SM_RESP status
• Store Message IDs: Save message_id for tracking
• Handle Throttling: Implement retry logic for ESME_RTHROTTLED
• Validate Numbers: Ensure phone numbers are in international format (+264...)

Error Handling

// Pseudo-code for error handling
if (response.command_status == ESME_RTHROTTLED) {
    // Wait and retry
    sleep(1000);
    retry_message();
} else if (response.command_status == ESME_RINVDSTADR) {
    // Invalid number - don't retry
    log_error("Invalid destination number");
    mark_as_failed();
} else if (response.command_status == ESME_ROK) {
    // Success
    save_message_id(response.message_id);
}

Performance

• Connection Pooling: Reuse connections instead of creating new ones
• Batch Processing: Send multiple messages per session
• Async Processing: Use async/await for non-blocking operations
• Rate Limiting: Respect server throttling limits

Security

• Secure Credentials: Never hardcode passwords in source code
• Use Environment Variables: Store credentials in config files or env vars
• Monitor Sessions: Track active sessions and detect anomalies
• IP Whitelisting: Request IP whitelisting for production systems

Server Security Features

• Rate Limiting: Maximum 300 messages per minute per session (ESME_RTHROTTLED response when exceeded)
• DoS Protection: 4KB maximum PDU size to prevent memory exhaustion attacks
• Session Limits: Maximum 100 concurrent sessions (configurable)
• Session Timeout: Automatic cleanup of inactive sessions after 300 seconds
• Password Masking: Passwords are masked in web portal (first 4 chars + ••••••••)
• Graceful Shutdown: Proper cleanup of all resources on server restart