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 with Docker Compose v2.
• curl and a POSIX shell.
• At least 1 GB of RAM and 2 GB of free disk space. For a more comfortable evaluation, 2 GB of RAM and 5 GB of free disk space are recommended.

Generate and Start Sendium

Download and run the setup script:

curl -fsSLo quick-start.sh https://raw.githubusercontent.com/cytechmobile/sendium/main/quick-start.sh && sh quick-start.sh

The script creates a sendium/ runtime directory, generates a native HTTP API key plus separate Kannel-compatible HTTP, SMPP and database credentials, writes Docker Compose and all required configuration files, starts PostgreSQL and Sendium, and waits for PostgreSQL-backed readiness.

It asks you to choose one upstream option:

1. ProSMS: Uses smpp.prosms.gr:2775 with a transceiver connection. Create a ProSMS account if needed; SMPP credentials require manual approval from ProSMS. Until credentials are approved, the script creates a local-only setup without a failing placeholder connection.
2. Existing SMPP provider: Enter your provider host, port, credentials, and TLS choice. Quick Start uses a transceiver connection.
3. Local setup only: Starts Sendium's local HTTP and SMPP interfaces without an outbound provider. You can explore the API, but messages cannot be delivered until an upstream route is configured.

HTTP and SMPP ports are bound to 127.0.0.1 by default. Use the Docker deployment guide for generated-file details, manual setup, native images, and non-local deployments. Review DLR persistence before changing database backends or volume handling.

When startup completes, the script prints the Swagger URL and an exact command for following live logs

Send Your First SMS

For a configured upstream provider, load the generated API key and submit through Sendium's native JSON API:

cd sendium
set -a
. ./.sendium.env
set +a

curl -i http://127.0.0.1:8080/api/v1/messages \
  -H "Authorization: Bearer ${SENDIUM_HTTP_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{"from":"Sendium","to":"306910000000","text":"Hello from Sendium!"}'

Replace the sender and recipient with values accepted by your provider. A 202 Accepted response with JSON containing messageId and status: "accepted" means Sendium validated and queued the request; it does not confirm that the upstream provider accepted or delivered the SMS.

For existing Kannel integrations, /sendsms remains available using the separately generated SENDIUM_HTTP_USER and SENDIUM_HTTP_PASSWORD; see the Kannel-compatible HTTP API. The two HTTP credentials share the configured quickstart-http account. If an older generated runtime has no SENDIUM_HTTP_API_KEY, rerun Quick Start with --force to regenerate credentials (existing client credentials rotate), or add a native API-key credential using the authentication guide.

See the Docker deployment guide for the complete manual container setup. Configuration details are maintained in Authentication and Security, SMPP Configuration, Routing Engine, and the Configuration Reference.

Optional: View Metrics in Grafana

For an operational view of SMS traffic, provider activity and application health, use the optional Prometheus and Grafana setup. It includes SMS Operations and Application Health dashboards.

Monitoring starts separately from Sendium and is not downloaded or started by quick-start.sh. Use the monitoring/ files from this repository and follow the setup guide to configure a Prometheus target reachable from its container; Docker network addresses can differ from the host's localhost:8080. No monitoring services are required to send SMS.

💬 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.

Migrating from Kannel? Use the browser-only Kannel migration converter to paste a legacy kannel.conf and generate Sendium starter files locally in your browser.

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.