📡 SMPP Server

The SMPP Server is a standalone SMPP v3.4 protocol service that bridges SMPP-compatible clients (SMS aggregators, messaging platforms) with the SMSGate ecosystem. It enables external systems to submit SMS messages and receive delivery receipts using the industry-standard SMPP protocol.

📖 Overview

The SMPP Server acts as a bridge between SMPP clients and the SMSGate REST API. It translates SMPP protocol operations into HTTP API calls, allowing existing SMPP-based infrastructure to work seamlessly with Android devices running the SMS Gateway app.

sequenceDiagram
    participant Client as SMPP Client<br/>(ESME)
    participant SMPP as SMPP Server
    participant Gateway as SMSGate REST API
    participant Device as Android Device

    Client->>SMPP: BIND_TRX (system_id/password)
    SMPP->>Gateway: Validate credentials (GET /devices)
    SMPP->>Gateway: Register webhook for receipts
    SMPP-->>Client: BIND_RESP (success)

    Client->>SMPP: SUBMIT_SM
    SMPP->>Gateway: POST /api/3rdparty/v1/messages
    Gateway->>Device: Send SMS
    Gateway-->>SMPP: Message ID
    SMPP-->>Client: SUBMIT_SM_RESP (message_id)

    Device-->>Gateway: Delivery status
    Gateway-->>SMPP: Webhook callback
    Note over SMPP: DELIVER_SM forwarding (WIP)
    SMPP-->>Client: DELIVER_SM

🏗️ Architecture

The SMPP Server is a standalone Go service with no shared database. All communication with the SMS Gateway happens via the REST API using the client-go SDK.

☁️ Public SMPP Server

A public SMPP server is available at smpp.sms-gate.app — no installation or self-hosting required. Connect directly using your SMSGate credentials.

Comparison: Public vs Self-Hosted

Self-Hosted Deployment

Option A: Pre-built Binary

Download the latest release binary from GitHub Releases:

curl -LO https://github.com/android-sms-gateway/smpp-server/releases/latest/download/smpp-server_Linux_x86_64.tar.gz
tar -xzf smpp-server_Linux_x86_64.tar.gz
./smpp-server

Option B: Docker

Pull and run the Docker image from GitHub Container Registry:

docker run \
  -p 2775:2775 \
  -e SMPP__BIND_ADDRESS=0.0.0.0:2775 \
  -e GATEWAY__API_BASE_URL=https://api.sms-gate.app/3rdparty/v1 \
  -e GATEWAY__WEBHOOK_BASE_URL=https://your-public-url \
  ghcr.io/android-sms-gateway/smpp-server:latest

Option C: Build from Source

git clone https://github.com/android-sms-gateway/smpp-server.git
cd smpp-server
go build -o smpp-server .
./smpp-server

⚙️ Configuration

Configuration is loaded via environment variables or a .env file. An optional YAML config file can be specified via the CONFIG_PATH environment variable.

🔐 Authentication

SMPP clients authenticate using their SMSGate credentials via the BIND sequence:

The authentication flow:

1. Client sends a BIND PDU with system_id (SMSGate username) and password
2. SMPP Server validates credentials against the SMSGate REST API
3. On success, the session is established and the client can send/receive PDUs
4. For RECEIVER and TRANSCEIVER binds, a dynamic webhook is registered for delivery receipts
5. On UNBIND, the webhook is deregistered and the session is cleaned up

📡 SMPP Operations

Supported PDUs

Unsupported PDUs

The following PDUs are recognized but return error responses:

• DATA_SM — Not supported
• CANCEL_SM — Not supported
• REPLACE_SM — Not supported
• SUBMIT_MULTI — Not supported

🔒 TLS/SMPPs Configuration

To enable encrypted SMPP connections (SMPPs), provide TLS certificate and key paths:

docker run \
  -p 2776:2776 \
  -v /path/to/certs:/certs:ro \
  -e SMPP__TLS_CERT=/certs/server.crt \
  -e SMPP__TLS_KEY=/certs/server.key \
  -e SMPP__BIND_ADDRESS=0.0.0.0:2776 \
  ghcr.io/android-sms-gateway/smpp-server:latest

📬 Delivery Receipts

When using BIND_RECEIVER or BIND_TRANSCEIVER, the SMPP Server automatically:

1. Registers a webhook with the SMSGate upon successful bind
2. Receives delivery status updates via webhook callbacks
3. Maps gateway message states to SMPP message_state values

Message State Mapping

🚀 Deployment

Docker Compose Example

services:
  smpp-server:
    image: ghcr.io/android-sms-gateway/smpp-server:latest
    ports:
      - "2776:2776"
      - "3000:3000"
    environment:
      - SMPP__BIND_ADDRESS=0.0.0.0:2776
      - SMPP__TLS_CERT=/certs/server.crt
      - SMPP__TLS_KEY=/certs/server.key
      - GATEWAY__API_BASE_URL=https://api.sms-gate.app/3rdparty/v1
      - GATEWAY__WEBHOOK_BASE_URL=https://smpp.example.com
      - GATEWAY__TIMEOUT=60s
    volumes:
      - ./certs:/certs:ro
    restart: unless-stopped

Health Check

The built-in health endpoint is available at GET /health on the HTTP server (default port 3000):

curl http://localhost:3000/health

⚠️ Known Limitations

📚 See Also

• SMPP Protocol Integration
• SMSGate API Reference
• Certificate Authority
• SMPP Server GitHub Repository