This page is the main documentation entry point for Sendium users, operators, and contributors.
Sendium is an open-source, headless SMS gateway for high-throughput messaging. It sits between internal applications such as CRMs, websites, and IoT platforms and SMS connectivity such as carriers or SMPP providers. It is designed to help teams avoid vendor lock-in, control routing logic, and scale messaging across on-premise or cloud environments.
| Concept | Description |
|---|
| HTTP API | Kannel-compatible GET /sendsms endpoint for outbound message submission. |
| SMPP Server | Accepts SMPP binds from downstream clients and applications. |
| SMPP Client | Connects to upstream SMSCs, carriers, or SMPP providers. |
| Routing Engine | Evaluates routingTable.conf rules and sends messages to workers or routing chains. |
| DLR Forwarding | Sends delivery receipt status updates back to the originating HTTP system. |
| MO Forwarding | Sends incoming mobile-originated messages to HTTP webhooks. |
| Hot Reload | Credentials and routing files are monitored and reloaded without restarting the service. |
Sendium expects these files in the configured conf directory. The Docker quick start maps this directory to /work/conf.
| File | Purpose |
|---|
credentials.yml | Defines HTTP and SMPP authentication profiles. |
smsg.properties | Defines workers, SMPP server settings, SMPP client binds, logging, and forwarding options. |
routingTable.conf | Defines routing tables, rule conditions, and fallback behavior. |
| Document | Description |
|---|
| 01. Architecture Overview | Runtime components, queues, routing flow, worker lifecycle, DLR/MO handling, and Mermaid diagrams. |
| 02. Docker Deployment | Container setup, image variants, volumes, ports, startup checks, and operational notes. |
| 03. Authentication and Security | Credential file format, validation rules, IP allowlisting, and reload behavior. |
| 04. SMPP Configuration | SMPP server, SMPP client, worker, retry, TLS, logging, and MO settings. |
| 05. Routing Engine | Routing table syntax, operators, message attributes, and routing examples. |
| 06. HTTP API | Kannel-compatible HTTP submission endpoint, parameters, and response codes. |
| 07. Webhooks | DLR callback URLs and MO forwarding behavior. |
| 08. Monitoring And Observability | Prometheus metrics endpoint, Prometheus scrape configuration, Grafana setup, and troubleshooting. |
| 09. Configuration Reference | Application paths, Docker image tags, environment variables, logging, and OpenAPI endpoints. |
| 10. Troubleshooting | Common startup, authentication, routing, SMPP, webhook, and logging issues. |
| 11. Release Process | Release Please flow, Conventional Commit rules, release PR handling, GitHub Packages, and Docker publishing. |
| 12. Features And Roadmap | Current product capabilities, planned roadmap phases, and related feature documentation. |
| Kannel migration converter | Browser-only helper for turning a legacy kannel.conf into Sendium starter files. |
When Sendium is running, the HTTP API can be inspected through:
| Endpoint | Description |
|---|
/sendsms | Kannel-compatible SMS submission endpoint. |
/swagger-ui | Interactive Swagger UI. |
/openapi.json | OpenAPI specification. |
/q/metrics | Prometheus-compatible Micrometer metrics endpoint. |
| File | Description |
|---|
| README | Project overview, capabilities, and quick start. |
| Contributing | Local setup, tests, style, and pull request process. |
| Code of Conduct | Community behavior expectations and reporting process. |
| Support | Where to ask questions, report bugs, and request features. |
| Security | Private vulnerability reporting policy. |
| License | GPL-3.0 license. |
- Read the README for the project overview.
- Read Architecture Overview to understand the runtime components and message flow.
- Follow Docker Deployment to start a local gateway.
- Configure access in Authentication and Security.
- Configure binds in SMPP Configuration.
- Configure message flow in Routing Engine.
- Submit a test message using HTTP API.
- Add delivery callbacks using Webhooks.
- Monitor the service using Monitoring And Observability.
- Review current and planned product scope in Features And Roadmap.
- Learn how releases are created and published in Release Process.
These are useful follow-up docs for future contributors:
| Proposed Topic | Why it matters |
|---|
| Production operations guide | Covers sizing, persistence, upgrades, backups, alerting, and maintenance. |
| Configuration examples directory | Gives copy-paste examples for common SMPP and routing scenarios. |
| Message encoding guide | Explains GSM, Latin-1, UCS-2, binary messages, UDH, and multipart SMS. |
| SMPP error-code mapping guide | Helps operators map provider-specific errors to Sendium retry/fail behavior. |