Changelog

Overview

Major security and stability improvements to the SMPP Server service, enhancing protection against attacks and improving resource management for enterprise-grade reliability.

Security Enhancements

Rate Limiting Protection

• Implemented 300 messages per minute limit per SMPP session
• Automatic throttling with ESME_RTHROTTLED response
• In-memory tracking for optimal performance
• Prevents abuse and ensures fair resource allocation

DoS Attack Prevention

• 4KB maximum PDU size validation to prevent memory exhaustion
• Automatic connection termination on invalid PDU sizes
• Session limit enforcement (100 concurrent sessions)
• Automatic timeout of inactive sessions (300 seconds)

API Key Authentication

• New: SMPP authentication now uses API keys instead of account passwords
• System ID: User email address (e.g., info@example.com)
• Password: First 8 characters of API key (SMPP protocol limitation)
• API keys displayed with masking in web portal (e.g., rqym••••••••)
• Improved security - API keys can be rotated without changing account password
• Aligns with REST API authentication mechanism

Channel Routing & Billing

Automatic Channel Routing

• New: PDU source_addr field is now ignored
• Messages automatically routed using user's default channel from database
• Ensures correct billing and routing through assigned SMS channels
• Matches REST API behavior for consistent channel management
• Eliminates ESME_RINVSRCADR errors from invalid sender IDs

Billing Flexibility

• Removed pre-submission billing rate validation
• Messages accepted without configured rates (unit_cost defaults to 0.00)
• Billing performed after MNO reconciliation (SMS Gateway model)
• Prevents message rejection due to missing rate configuration
• Supports dynamic pricing and post-paid billing models

Stability Improvements

Resource Management

• Fixed memory leak in SMPP server instance management
• Implemented graceful shutdown with proper resource cleanup
• Thread-safe reference ID generation using Interlocked operations
• Proper TcpClient disposal to prevent connection leaks

Session Management

• Added LastActivity tracking for accurate session timeout
• ENQUIRE_LINK keepalive now properly updates session activity
• Improved session cleanup on disconnect
• Enhanced exception logging for better debugging

Documentation Updates

• Updated SMPP Server technical documentation
• Added security features section to developer portal
• Documented all rate limiting and DoS protection mechanisms
• Updated code examples with new constructor signatures

Technical Details

Authentication:

• System ID: User email address from client_user table
• Password: LEFT(api_key, 8) - first 8 characters only
• Default channel retrieved from client_user.channel during bind
• SQL query validates: email, API key (8 chars), status=1, active=true

Message Routing:

• PDU source_addr field ignored (any value accepted)
• Channel from database used for all outgoing messages
• Destination format: International without + prefix (e.g., 264811234567)
• Messages inserted into sms_outgoing with correct channel and unit_cost

Security & Performance:

• Maximum PDU size: 4KB (enforced at protocol level)
• Rate limit: 300 messages/minute per session
• Session timeout: 300 seconds of inactivity
• Max concurrent sessions: 100 (configurable)
• All security features enabled by default

Migration Guide:

• Action Required: Update SMPP clients to use API key (first 8 chars) instead of account password
• System ID remains the same (email address)
• Source address in PDU can be any value (will be ignored)
• No billing rate configuration needed - messages accepted for post-reconciliation billing
• See updated documentation: /developer/api.smpp.html

Overview

Revolutionary new feature enabling opt-in/opt-out subscription management via web links, specifically designed for alphanumeric sender IDs that cannot receive SMS replies. Users can now click a link in their SMS to manage their subscription preferences through a beautiful web interface.

Key Features

Public Subscription API

No Authentication Required - User-Friendly Access

• Public GET endpoints for opt-out and opt-in actions
• Beautiful, mobile-responsive HTML confirmation pages
• Instant database updates with audit trail
• Mobile number normalization (handles +264, 0, etc.)
• Client name lookup for personalized messages

API Endpoints:

GET /sms/2/messages/subscription/{clientid}/opt/out/{mobile}
GET /sms/2/messages/subscription/{clientid}/opt/in/{mobile}

Example Usage in SMS:

SchoolSMS: Your child has been marked absent today.
Opt-out: https://sms.com.na/u/abc123

Portal Configuration

Easy Setup in Web Portal

• New opt-out and opt-in link configuration fields
• Default base URL pre-filled: https://{host}/sms/2/messages/subscription/
• Copy-to-clipboard functionality for generated links
• Support for custom opt-out pages
• Clear guidance for alphanumeric channels

Configuration Location:

Portal → Account → SMS Channels → Select Channel → Opt-out Link for Alphanumeric Channels

Comprehensive Documentation

Complete Developer Guide

• Full API reference with examples
• SMS composition guide (how to write messages with opt-out links)
• Good vs bad examples with character counts
• URL shortening recommendations (Bitly, TinyURL, custom domain)
• Legal compliance checklist
• Multi-part SMS cost analysis

Documentation Highlights:

• SMS Composition: 6 opt-out wording options, character optimization tips
• Examples: School notifications, marketing, appointment reminders
• Best Practices: 8-point guide for effective implementation
• Cross-Links: Integrated with webhook documentation

The Problem This Solves

Alphanumeric Sender IDs Cannot Receive SMS

Technical Implementation

Backend Components:

• New public endpoints in SMSApiModule.cs
• HTML response rendering with modern, mobile-first design
• Direct database operations via execute.ExecuteNonQuery()
• Comprehensive logging for debugging

Database Schema:

• New columns: opt_out_link_base, opt_in_link_base
• Migration: v4.8.52_add_subscription_link_fields.sql
• Audit trail in contacts.status_description

Webportal Updates:

• New UI fields in sms_channel.aspx
• JavaScript copy-to-clipboard functionality
• Backend save operation updated

Documentation Files

New Files:

• /developer/api.subscription.html - Complete subscription API reference
• WEB_BASED_SUBSCRIPTION_MANAGEMENT.md - Technical documentation

Updated Files:

• /developer/index.html - Added subscription management card
• /developer/webhooks.index.html - Cross-link to subscription API
• /developer/webhooks.optout.html - Warning for alphanumeric channels
• /developer/webhooks.optin.html - Warning for alphanumeric channels

Use Cases

Overview

Major documentation overhaul making SMSDESK deployment-agnostic and enterprise-ready. Complete rebranding from deployment-specific references to generic SMSDESK product documentation suitable for all customers and deployment scenarios.

Key Features

Comprehensive Configuration Guide

New Portal Configuration Documentation

• Step-by-step portal configuration walkthrough
• Direct references to web portal screens and fields
• SMS channel setup and webhook configuration
• API key generation and management
• Complete testing procedures
• Troubleshooting guides for common issues

Enhanced Webhook Documentation

Production-Ready Code Examples

• Verified HMAC-SHA256 signature verification code
• Working examples in Python, C#, JavaScript, and PHP
• Security best practices and constant-time comparison
• Complete webhook payload structures verified from source code
• Integration examples for all webhook types (DLR, Incoming SMS, Opt-in/out)

Webhook Types Documented:

• Delivery Reports (DLR): Real-time message delivery status
• Incoming SMS: Receive SMS messages via webhooks
• Opt-in: Handle subscription requests
• Opt-out: Handle unsubscribe requests

Technical Improvements

Documentation Accuracy:

• All webhook payloads verified against actual source code
• Status codes confirmed from implementation (0, 1, 2, 4, 9)
• HMAC signature format verified (X-Signature: sha256=<hex>)
• Portal field mappings documented (txt_dlr_webhook_url, txt_security_key, etc.)

Code Examples:

• Python: Flask-based webhook receiver with constant-time comparison
• C#: ASP.NET Core with cryptographically secure verification
• JavaScript: Node.js/Express with timing-safe comparison
• PHP: Using hash_equals for security

Portal Integration:

• Direct links to portal configuration screens
• Field-by-field mapping documentation
• Security key generation instructions
• Complete webhook setup examples

Documentation Files

New Files:

• /developer/configuration_guide.html - Complete portal setup guide
• /_webhook_hmac_examples.html - Reusable HMAC verification code

Updated Files:

• /developer/index.html - Added configuration guide link
• /developer/webhooks.*.html - Branding and portal references updated
• /http/index.html - Version number added to footer

Overview

Enhanced SMS status tracking with additional query options and detailed status information for better message monitoring and troubleshooting.

Key Features

Enhanced Status Endpoint

New Query Options

• Query by internal SMS ID for direct database lookups
• Access detailed SMPP status information
• View scheduled message timestamps
• Retrieve raw status codes for advanced integrations

Endpoint: GET /sms/2/reports

New Query Parameters:

• smsId - Query by internal database ID for precise lookups
• Enhanced response with additional status fields

Enhanced Response Fields:

{
  "smsId": 123456,
  "statusCode": 3,
  "axStatusDesk": "DELIVRD",
  "scheduledTime": "2026-07-11T10:00:00Z",
  "status": {
    "name": "DELIVERED",
    "description": "Message delivered to handset"
  }
}

Technical Improvements

API Enhancements:

• Optimized status queries for faster response times
• Consistent endpoint naming conventions
• Improved documentation with additional examples

Documentation Updates:

• Updated API reference with new parameters
• Added code examples for status queries
• Enhanced troubleshooting guides

Overview

Major security enhancement introducing modern header-based API authentication alongside comprehensive API documentation updates.

Key Features

Enhanced API Authentication

Modern Header-Based Authentication

• Support for X-API-Key header (recommended)
• Support for Authorization: Bearer token format
• Support for Authorization: ApiKey format
• Fully backward compatible with existing query parameter authentication

Example Usage:

curl -X POST https://{host}/sms/2/messages \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json"

Improved API Key Generation

Cryptographically Secure Keys

• 64-character mixed-character API keys
• Generated using Web Crypto API
• Enhanced entropy for better security
• Automatic fallback for older browsers

Key Characteristics:

• Uppercase and lowercase letters
• Numbers and special characters
• Cryptographically random generation
• Unique per channel

Comprehensive API Documentation

New Basic API Documentation

• Complete reference for legacy HTTP API
• Header-based authentication examples
• Code samples in 6 programming languages
• Best practices and security guidelines

Documentation Highlights:

• Python, PHP, JavaScript, C#, Java, and cURL examples
• Clear migration paths from legacy methods
• Security recommendations
• Troubleshooting guides

Technical Improvements

Authentication Flow:

1. Check X-API-Key header (preferred)
2. Check Authorization header with Bearer/ApiKey schemes
3. Fall back to query/form parameters (legacy support)
4. Validate against database

Database Compatibility:

• Enhanced PostgreSQL type handling
• Improved boolean field compatibility
• Optimized query performance

Overview

Major feature release adding full support for delivery report webhooks with HMAC-SHA256 signatures, enabling real-time delivery notifications to customer endpoints.

Key Features

Delivery Report (DLR) Webhooks

Automated Delivery Notifications

• Real-time webhook notifications when SMS delivery reports are received
• HMAC-SHA256 signed requests for security and authenticity
• Automatic retry logic with exponential backoff (3 attempts)
• Fire-and-forget async processing (non-blocking)

How It Works:

1. Delivery report received from carrier via SMPP
2. Automatically matched to original outgoing message
3. Webhook POST sent to your configured endpoint
4. Includes message ID, status, delivery timestamp, and more

Webhook Payload Example:

{
  "type": "delivery_receipt",
  "timestamp": "2026-07-09T07:00:00Z",
  "data": {
    "messageId": "123456",
    "status": "DELIVERED",
    "statusCode": 2,
    "mobile": "+27821234567",
    "deliveredAt": "2026-07-09T06:59:55Z"
  }
}

Documentation Enhancements

Updated Developer Portal

• Complete webhook integration guide
• HMAC-SHA256 signature verification examples
• Code samples in C#, Node.js, and PHP
• Testing and troubleshooting guides

Overview

This release focuses on performance optimization and improved user experience through streamlined reporting and cleaner system logs.

Key Features

Outgoing Reports Optimization

Simplified Report Selection

• Reports now use Year + Month selection instead of date ranges
• Faster query performance through optimized data tier selection
• Cleaner, more intuitive user interface

Smart Data Tier Selection

The system automatically queries the most efficient data source:

• Recent data (last 24 hours): Live production tables
• Historical data (1 day - 3 months): Archive tables
• Long-term data (older than 3 months): Partitioned archive storage

Technical Improvements

Performance Enhancements

• Intelligent query routing with automatic data source selection
• Reduced query complexity
• Improved response times for all time periods

Logging Improvements

• Reduced verbose logging for routine operations
• Focus on important events and errors
• Improved readability for system monitoring