A comprehensive, hands-on, 5-day training program for deploying and operating a production-ready bulk SMS sending system using Jasmin SMS Gateway, the open-source SMS gateway that speaks SMPP upstream to carriers/SMSCs and exposes both SMPP Server and HTTP (REST) API interfaces downstream to your own applications.
⚠️ Verify before deploying: Jasmin is an actively developed open-source project; default ports,jclicommands, and configuration file locations can change between versions. This README defines the training structure and objectives against the documented architecture (SMPP Client/Server, HTTP API, RabbitMQ/Redis-backed routing). Confirm exact syntax and defaults against the version you deploy — see Additional Resources.
- Overview
- Learning Objectives
- Audience
- Prerequisites
- Lab Environment
- Training Schedule
- Repository Structure
- Getting Started
- Lab Exercises
- Assessment & Certification
- Reference Architecture
- Troubleshooting Guide
- Additional Resources
- Contributing
- License
This training module prepares infrastructure and messaging engineering teams to deploy, configure, and operate Jasmin SMS Gateway as the core of a self-hosted bulk SMS platform. Unlike a hosted SMS provider, Jasmin sits in the middle of the messaging chain: it binds upstream to one or more carriers/SMSCs/aggregators over SMPP as a client, and exposes downstream interfaces — its own SMPP Server and a RESTful HTTP API — for your applications to send and receive SMS through. The course covers the full lifecycle: installation, upstream SMPP connector configuration, downstream API/server setup, message routing and filtering, two-way (MT/MO) messaging, delivery receipt (DLR) handling, billing/quota management, and production-grade operations including high availability and monitoring.
By the end of this training, participants will be able to:
- Explain Jasmin's architecture: SMPP Client Manager, SMPP Server API, HTTP API, the AMQP (RabbitMQ) message broker backbone, and Redis-backed DLR/billing tracking
- Install and run Jasmin (Docker, package, or source) alongside its RabbitMQ and Redis dependencies
- Use the
jclimanagement console to configure connectors, users, groups, and routes without service restarts - Establish an SMPP Client connector to bind Jasmin to an upstream carrier/SMSC (using a simulator for lab purposes)
- Send and receive SMS using Jasmin's HTTP API for application integration (MT sends, MO/DLR callbacks)
- Configure Jasmin's SMPP Server API so that third-party applications can bind to Jasmin as their own SMSC
- Design MO and MT routing tables using Jasmin's filter system (destination address, date/time interval, user, group, and more) and routing strategies (Simple, Round-robin, Failover, Least Cost, HLR lookup)
- Implement two-way SMS: receiving MO messages, correlating delivery receipts, and building auto-reply/keyword logic
- Manage Users, Groups, and quotas for multi-tenant or aggregator-style deployments, including basic billing/credit control
- Handle Unicode, concatenated (long) SMS, and binary message types (WAP Push, vCard, ringtones)
- Secure, monitor, and scale a Jasmin deployment for production: throughput tuning, Prometheus/Grafana metrics, high availability, and operational runbooks
- Telecom/VAS (value-added services) engineers building or operating an SMS gateway
- Backend/platform engineers integrating bulk and two-way SMS into internal or customer-facing systems
- DevOps/SRE teams responsible for deploying and operating self-hosted messaging infrastructure
- Aggregators/resellers needing multi-tenant routing, billing, and quota management for SMS traffic
Required:
- Working knowledge of Linux system administration
- Basic familiarity with Docker and Docker Compose
- Comfort with the command line
- Basic understanding of networking (TCP/IP, ports, firewalls)
Recommended:
- Prior exposure to message queues (AMQP/RabbitMQ) and Redis
- Familiarity with Python (Jasmin itself is Python/Twisted-based; useful for advanced customization)
- Basic understanding of telecom SMS concepts (SMSC, MT/MO, DLR)
Not required but helpful: Prior experience with any SMPP-based platform, prior exposure to another gateway (Kannel, SMSC simulators)
Each participant is provisioned with an isolated lab environment consisting of:
| Component | Specification |
|---|---|
| Control Node | 4 vCPU / 8 GB RAM / 40 GB disk (Ubuntu 22.04) with Docker and Docker Compose |
| Jasmin Instance | Deployed via the official jookies/jasmin Docker image |
| Message Broker | RabbitMQ (with management plugin) |
| Cache/DLR Store | Redis |
| Upstream Simulator | An SMPP simulator (e.g., SMPPSim) standing in for a real carrier/SMSC, so binds and message flow can be tested without a live telecom contract |
| Monitoring | Prometheus + Grafana, using Jasmin's built-in /metrics endpoint and pre-made dashboards (HTTP API, SMPP Clients, SMPP Server) |
| Access | Browser-based terminal, jcli access via Telnet (port 8990), exposed SMPP (2775) and HTTP API (1401) ports |
💡 A fully local Docker Compose lab is the default path — see
/labs/environment-setup. A cloud-based multi-VM option (for HA labs on Day 5) is also provided.
Morning — Concepts
- SMS gateway fundamentals: MT (mobile terminated) vs. MO (mobile originated), SMSC role, and where Jasmin sits in the messaging chain
- Jasmin's high-level architecture: SMPP Client Manager, SMPP Server API, HTTP API, Router (MO/MT), DLR Thrower, DeliverSM Thrower — all coordinated via RabbitMQ (AMQP) with Redis for DLR/billing state
- Why Jasmin needs RabbitMQ and Redis, and what each is responsible for
- Deployment options: Docker image,
.deb/.rpmpackages, PyPI, Kubernetes - The
jclimanagement console: Telnet-based, console-driven configuration with no service restarts required
Afternoon — Hands-on Labs
- Lab 1.1: Deploy Jasmin, RabbitMQ, and Redis using Docker Compose
- Lab 1.2: Connect to
jclivia Telnet and explore the available modules (smppccm,httpccm,user,group,morouter,mtrouter) - Lab 1.3: Deploy an SMPP simulator (SMPPSim) to act as your lab "upstream carrier"
- Lab 1.4: Review Jasmin's log files and confirm all core services (SMPP Client Manager, HTTP API, Router) are healthy
Deliverable: A running Jasmin instance with RabbitMQ, Redis, and a simulated upstream SMSC, ready for connector configuration.
Morning — Concepts
- SMPP protocol fundamentals: binds (Transmitter/Receiver/Transceiver), core PDUs (
submit_sm,deliver_sm,enquire_link,unbind) - Jasmin's SMPP Client Manager: connector parameters (
cid,host,port,username,password, bind type,submit_throughput) - Connector lifecycle: add, configure, start, stop, and monitor a connector via
jcli'ssmppccmmodule - Throughput control at the connector level (
submit_throughput) and its role in respecting upstream carrier limits - Delivery receipts (DLRs): how Jasmin tracks them via Redis and maps them back to the originating message
Afternoon — Hands-on Labs
- Lab 2.1: Add an SMPP Client connector in
jclipointing to your lab SMPP simulator - Lab 2.2: Start the connector and confirm a successful bind (transceiver mode)
- Lab 2.3: Send a test MT message through the connector directly via
jcliand confirm delivery at the simulator - Lab 2.4: Configure
submit_throughputand observe its effect on submission rate under load - Lab 2.5: Trigger a delivery receipt from the simulator and trace it through Jasmin's DLR handling
Deliverable: A working, throughput-controlled SMPP Client connector bound to the lab upstream simulator, with confirmed DLR handling.
Morning — Concepts
- Jasmin's HTTP API: RESTful endpoints for sending MT messages, checking balance, and application integration patterns
- Configuring HTTP throwers for MO (inbound) messages and DLR callbacks to your application's webhook
- Jasmin's SMPP Server API: allowing third-party applications to bind to Jasmin itself as if it were an SMSC — binds, authentication, and use cases (e.g., legacy systems that only speak SMPP)
- Choosing HTTP API vs. SMPP Server API for a given internal application, and when to expose both
- Users and Groups: provisioning application/API credentials with per-user quotas and permissions
Afternoon — Hands-on Labs
- Lab 3.1: Create a Group and a User in
jcli, and generate HTTP API credentials for that user - Lab 3.2: Send an MT SMS via the HTTP API (
curl/SDK) routed through your Day 2 SMPP connector - Lab 3.3: Configure an HTTP MO thrower pointing at a lab webhook receiver and confirm inbound message delivery
- Lab 3.4: Configure the SMPP Server API and bind a second Jasmin SMPP client (simulating a third-party application) directly to your Jasmin instance
- Lab 3.5: Build a simple two-way flow: HTTP API sends an outbound message, MO webhook receives a reply, application logic sends an automated response
Deliverable: A dual-interface Jasmin gateway: applications can send/receive via HTTP API or bind directly via SMPP Server API, both routed through the same upstream connector.
Morning — Concepts
- The Message Router: separate MO Routing Table and MT Routing Table, each holding ordered Route objects with attached Filters
- Filter types: destination address (regex), date interval, time interval, user/group, source connector, and more
- Routing strategies: Simple, Round-robin (load distribution across multiple connectors), Failover (automatic fallback), Least Cost Routing, HLR lookup-based routing
- Designing a bulk-send pipeline: queueing personalized messages, distributing load across multiple upstream connectors, and respecting per-connector throughput
- Handling Unicode (UTF-8) messages and concatenated (long) SMS across the pipeline
- Multi-tenant considerations: routing by user/group for aggregator-style deployments
Afternoon — Hands-on Labs
- Lab 4.1: Add a second SMPP Client connector (a second simulated upstream) and configure Round-robin routing across both
- Lab 4.2: Build an MT route using a
DestinationAddrFilterto route specific number prefixes to a specific connector - Lab 4.3: Configure Failover routing so traffic automatically shifts to a backup connector if the primary bind drops
- Lab 4.4: Build a bulk-send client application (queue + HTTP API workers) that imports a CSV contact list and sends personalized, throttled bulk messages through the routed pipeline
- Lab 4.5: Test Unicode and long-message (concatenated SMS) handling end-to-end through the pipeline
Deliverable: A multi-connector Jasmin routing configuration with load distribution and failover, plus a working bulk-send client application driving it via the HTTP API.
Morning — Concepts
- Billing and quotas: per-user/per-group MT/MO quotas, credit-based billing models, and premium content charging
- Security hardening: firewalling the SMPP (2775), HTTP API (1401), and
jcli(8990) ports; connection rate-limiting (e.g., iptables recent-match rules); log privacy (log_privacy) to avoid leaking message content - High availability patterns: running multiple Jasmin instances behind a shared RabbitMQ/Redis backend, connector redundancy, and failover design
- Monitoring: Jasmin's
/metricsendpoint, pre-built Grafana dashboards (HTTP API, SMPP Clients, SMPP Server, RabbitMQ overview) - Capacity planning: tuning
submit_throughputper connector, RabbitMQ queue depth monitoring, and scaling worker throughput - Operational runbooks: credential rotation, connector failover drills, and incident response for upstream outages
Afternoon — Hands-on Labs
- Lab 5.1: Configure per-user quotas and a simple credit-based billing rule in
jcli - Lab 5.2: Apply security hardening: restrict
jcli/SMPP/HTTP ports via firewall rules and enablelog_privacy - Lab 5.3: Stand up Prometheus + Grafana against Jasmin's
/metricsendpoint and explore the pre-made dashboards - Lab 5.4: Simulate an upstream connector outage and verify Failover routing and alerting behave as expected
- Lab 5.5 (Capstone): Deploy the complete system end-to-end — multi-connector routing with failover, HTTP API and SMPP Server API both active, user/group quotas, security hardening, and a live monitoring dashboard — and document it in an operational runbook
Deliverable (Capstone Project): A fully operational, secured, monitored, production-ready Jasmin SMS Gateway deployment with multi-connector routing, dual downstream interfaces, billing/quotas, and a written operational runbook.
jasmin-sms-gateway-training/
├── README.md
├── slides/ # Day-by-day presentation decks
│ ├── day1-fundamentals-and-deployment.pdf
│ ├── day2-smpp-client-connectors.pdf
│ ├── day3-http-api-and-smpp-server.pdf
│ ├── day4-routing-and-bulk-pipeline.pdf
│ └── day5-ha-security-and-operations.pdf
├── labs/
│ ├── environment-setup/ # Docker Compose bootstrap (Jasmin, RabbitMQ, Redis, SMPPSim, Prometheus/Grafana)
│ ├── day1/
│ ├── day2/
│ ├── day3/
│ ├── day4/
│ └── day5/
├── jcli-scripts/
│ ├── connectors/ # smppccm connector configuration scripts
│ ├── users-groups/ # user/group provisioning scripts
│ └── routing/ # morouter/mtrouter route definitions
├── app/
│ ├── http-api-client/ # Reference HTTP API send/receive implementation
│ ├── smpp-server-client/ # Reference client binding to Jasmin's SMPP Server API
│ └── bulk-queue/ # Queue producer/consumer, throttling, retry logic
├── monitoring/
│ └── grafana-dashboards/ # Jasmin metrics dashboard definitions
├── solutions/ # Reference solutions for each lab
└── docs/
├── troubleshooting.md
├── architecture-diagrams/
└── glossary.md
-
Clone this repository:
git clone https://github.com/<your-org>/jasmin-sms-gateway-training.git cd jasmin-sms-gateway-training
-
Provision your lab environment:
cd labs/environment-setup docker compose up -d -
Verify prerequisites:
./labs/environment-setup/scripts/check-prereqs.sh
-
Connect to jcli:
telnet 127.0.0.1 8990 # Default lab credentials: jcliadmin / jclipwd (change before any non-lab use) -
Start with Day 1:
cd labs/day1 cat README.md
Each day's lab folder (labs/dayN/) contains:
README.md— step-by-step instructions and success criteriastarter/— starting-point configs and codehints.md— progressive hints for anyone who gets stuck- Corresponding reference solution in
solutions/dayN/
Labs build cumulatively: the connector from Day 2, the API/server setup from Day 3, and the routing table from Day 4 are all assembled into the Day 5 capstone deployment.
- Daily checkpoints: short knowledge checks at the end of each day
- Capstone project (Day 5): graded on functionality, routing/failover correctness, security hardening, and monitoring completeness
- Certificate of completion issued to participants who complete all daily labs and the capstone project
The course builds toward the following bulk SMS gateway architecture:
Your Applications Upstream Carriers / SMSCs
┌─────────────────┐ ┌─────────────────────┐
│ HTTP API Client │ │ Carrier A (SMPP) │
│ (bulk queue, │ └──────────┬───────────┘
│ webhooks) │ │
└─────────┬───────────┘ ┌──────────▼───────────┐
│ │ Carrier B (SMPP) │
┌─────────▼───────────┐ └──────────┬───────────┘
│ Third-party App │ │
│ (binds via SMPP │ ┌──────────▼───────────┐
│ Server API) │────────────────────▶│ SMPP Client Manager │
└─────────────────────────┘ binds as ESME │ (connectors, TRX/TX/RX,│
│ submit_throughput) │
┌─────────────────────────────────────────────────┴───────────────────────┘
│ JASMIN SMS GATEWAY
│ ┌─────────────┐ ┌───────────────┐ ┌──────────────────────────┐
│ │ HTTP API │ │ SMPP Server API │ │ Message Router (MO/MT) │
│ └──────┬──────┘ └────────┬──────┘ │ Filters + Strategies: │
│ │ │ │ Simple / Round-robin / │
│ └──────────┬──────────┘ │ Failover / Least Cost / │
│ │ │ HLR lookup │
│ ┌─────────▼─────────┐ └──────────────────────────┘
│ │ RabbitMQ (AMQP) │◀────────────────────┘
│ │ + Redis (DLR/billing)│
│ └───────────────────┘
└───────────────────────────────────────────────────────────────────────────
Cross-cutting: Users/Groups/Quotas, Prometheus/Grafana Monitoring, jcli Console
See docs/architecture-diagrams/ for detailed diagrams per day.
Common issues and resolutions are documented in docs/troubleshooting.md, covering:
- SMPP Client connector fails to bind (credential mismatch, wrong bind type, network/firewall issues)
- Jasmin waiting indefinitely at startup (RabbitMQ or Redis not yet reachable)
- Messages accepted by
jcli/HTTP API but never leaving the connector (routing table misconfiguration, no matching route) - Delivery receipts not arriving (DLR request flag not set on submit, Redis mapping expired)
- HTTP MO/DLR webhooks not firing (thrower misconfiguration, unreachable application endpoint)
- Throughput bottlenecks (connector
submit_throughputtoo low, RabbitMQ queue backlog)
Jasmin is actively developed — always confirm current
jclisyntax, default ports, and configuration details against the version you deploy.
- Jasmin SMS Gateway Documentation: https://docs.jasminsms.com
- Jasmin GitHub Repository: https://github.com/jookies/jasmin
- Jasmin on PyPI: https://pypi.org/project/jasmin/
- Jasmin Architecture Overview: https://docs.jasminsms.com/en/latest/architecture/
- Jasmin Community Support Forum: https://groups.google.com/forum/#!forum/jasmin-sms-gateway
- SMPP Protocol Specifications (background reference): https://smpp.org
Contributions to improve labs, fix errata, or add advanced modules are welcome. Please open an issue or submit a pull request following the guidelines in CONTRIBUTING.md.
This training material is released under the MIT License. Jasmin SMS Gateway itself is released under the Apache License 2.0 — see the Jasmin project for details.
Questions or feedback? Open an issue in this repository or contact the training team.