Sendium | Open-Source Headless SMS Gateway

Sendium is an open-source, headless SMS gateway engineered for high-throughput delivery. Designed to sit seamlessly between your internal applications (CRMs, websites, IoT platforms) and your SMS connectivity (carriers, SMPP providers), it puts you firmly in control of your messaging infrastructure.

Eliminate vendor lock-in, manage your own routing logic, and scale your messaging horizontally across any on-premise or cloud environment.

---

🚀 Why Sendium?

• Modern Stack: A practical, container-native Kannel replacement built on Java & Quarkus.
• Total Control: Manage connections, adjust routing on the fly, and dictate fail-over rules.
• Protocol Agnostic: Bridge the gap between modern HTTP webhooks and legacy SMPP infrastructure.
• High Throughput: Designed for low latency and massive scale.

---

🏢 Backed by Cytech

Sendium is proudly created and maintained by Cytech.

With over 20 years of experience building high-performance telecommunications software, we open-sourced Sendium to provide the community with a modern, reliable Kannel alternative. Sendium is also the underlying routing engine that powers mCore, our complete enterprise business platform.

---

🛠 Core Capabilities

Feature	Description
SMPP Server & Client	Full TX/RX/TRX bind support for downstream clients and upstream carriers, including TLS/SSL options.
HTTP & SMPP Bridging	Kannel-compatible HTTP /sendsms API for outbound SMS and SMPP-to-HTTP webhooks for inbound MO traffic.
Advanced Routing	Route by destination, sender ID, content, account, or message attributes with fallback routing chains.
Granular TPS Control	Protect links with Transactions-Per-Second limits per worker or SMPP server account defaults.
Retry & Queue Control	Retry and re-enqueue messages when submit_sm to an SMPP provider fails, with priority-aware queue support.
Delivery Receipts	Correlate provider message IDs, normalize DLR statuses, and propagate callbacks to originating systems.
Operations & Observability	Docker/native images, hot-reloaded configuration, operational logs, Swagger/OpenAPI, and Prometheus /q/metrics.

---

🔄 How It Works

1. Request: Your application sends a message to Sendium via HTTP or SMPP.
2. Logic: Sendium applies routing rules based on destination, sender ID, account, message attributes, and priority.
3. Delivery: Sendium delivers via one or more SMPP connections to upstream providers.
4. Verification: Asynchronous Delivery Receipts (DLRs) are received and normalized.
5. Callback: Sendium forwards the status back to your system via HTTP Webhooks.

---

📦 Quick Start

Prerequisites

• Docker installed on your host machine.
• Create three empty directories in your current working folder: ./conf, ./data, and ./logs.
• Before starting the container, Sendium requires three configuration files inside ./conf. These files control your binds, authentication, and routing logic.

Create the following three files inside ./conf and adapt the sample configurations:

1. credentials.yml

• Setting smpp and http credentials on sendium

credentials:
  - type: SMPP
    systemId: "sendium-smpp-user"
    password: "change-me-smpp"
  - type: HTTP
    systemId: "sendium-http-user"
    password: "change-me-http"

2. smsg.properties

• Setting a smpp client connection and the smpp server.

# sample smpp client worker
outSms.instance.testRoute.enable = true
outSms.instance.testRoute.type = smppclient
outSms.instance.testRoute.username = upstream-system-id
outSms.instance.testRoute.password = upstream-password
outSms.instance.testRoute.host = smpp.test.com
outSms.instance.testRoute.port = 2775
outSms.instance.testRoute.tps = 0
outSms.instance.testRoute.connections.transceivers = 1

# smpp server
outSms.instance.smpp.enable = true
outSms.instance.smpp.type = smppserver
outSms.instance.smpp.tps = 0
outSms.instance.smpp.srv.port = 27777
outSms.instance.smpp.srv.defaultWindowSize = 1000
outSms.instance.smpp.srv.maxConnections = 1000
outSms.instance.smpp.srv.maxConnectionsPerIP = 4
outSms.instance.smpp.conf.maxConnectionsPerUser.default = 4
outSms.instance.smpp.conf.maxRate.default = 0

3. routingTable.conf

• Routing configuration for sending all traffic by default through the SMPP client named testRoute

[default]
MESSAGE:type:==:0
MESSAGE:type:==:11
MESSAGE:type:==:14
MESSAGE:type:==:17
MESSAGE:type:==:10
smppserver.smpp:type:==:18

[MESSAGE]
testRoute::default:

Running with Docker

Sendium publishes two Docker image variants:

Image	Runtime
cytechmobile/sendium:latest	JVM image based on Eclipse Temurin 25 JRE.
cytechmobile/sendium:latest-native	Native executable image.

Run the following command to start the default JVM image in the background:

docker run -d --name sendium \
  -e QUARKUS_LOG_FILE_ENABLE=true \
  -e QUARKUS_LOG_CONSOLE_ENABLE=false \
  -e QUARKUS_LOG_FILE_PATH=/work/logs/smsg.log \
  -e QUARKUS_LOG_FILE_SMPPCLIENT_PATH=/work/logs/smppclient.log \
  -e QUARKUS_LOG_FILE_SMPPSERVER_PATH=/work/logs/smppserver.log \
  -e QUARKUS_HTTP_ACCESS_LOG_DIRECTORY=/work/logs \
  -p 8080:8080 \
  -p 27777:27777 \
  -v ./conf:/work/conf \
  -v ./data:/work/data \
  -v ./logs:/work/logs \
  cytechmobile/sendium:latest

To run the native image instead, use cytechmobile/sendium:latest-native.

💬 Documentation & Support

The documentation entry point is docs/DocumentationMap.md. It includes the recommended reading order, current docs index, runtime files, API discovery endpoints, roadmap, and community resources.

Key docs:

1. Architecture Overview: Understand runtime components, queues, routing flow, workers, DLRs with diagrams.
2. Docker Deployment: Run Sendium with Docker, volumes, ports, logs, and startup checks.
3. Authentication & Security: Configure HTTP and SMPP credentials.
4. SMPP Configuration: Configure SMPP server, SMPP client, worker behavior, TLS, retries, and logging.
5. Routing Engine: Configure routing tables, rules, operators, and fallbacks.
6. HTTP API: Submit SMS through the Kannel-compatible /sendsms endpoint.
7. Webhooks: Configure DLR callbacks and MO forwarding.
8. Monitoring & Observability: Expose Prometheus metrics and configure Prometheus/Grafana.
9. Configuration Reference: Review paths, Docker environment variables, logging, and OpenAPI endpoints.
10. Troubleshooting: Diagnose common setup and runtime issues.
11. Release Process: Understand Release Please, Maven publishing, and Docker image publishing.
12. Features & Roadmap: Review current capabilities and planned roadmap phases.

When Sendium is running, API discovery is available at /swagger-ui and /openapi.json.

If you run into issues, have questions, or want to share what you're building, we'd love to hear from you! We use GitHub Discussions for our community hub.

To help us help you faster, please use the appropriate category:

• 🙏 Q&A: Stuck on the Quick Start? Need help with your routing config? Ask your questions here.
• 💡 Ideas: Have a feature request or a suggestion to make Sendium better? Let's discuss it.
• 🙌 Show and tell: Are you using Sendium in production? Did you build a cool integration? Share it with the community!
• 💬 General: For all other chats and discussions about the project.

Note: If you are confident you have found a bug, please open a formal GitHub Issue so we can track it.