Backend for the SMSGate ecosystem: a REST API that dispatches SMS/MMS through connected Android devices, with optional private deployment.

• 📱 SMSGate Server
  • 📚 Table of Contents
  • 📖 About
  • ⭐ Features
  • 📦 Prerequisites
  • 🚀 Quickstart
  • ⚙️ Configuration
    • Worker Tasks
  • 🔐 Authentication
  • 🔌 API Overview
  • 📚 Documentation
  • 🤝 Contributing
  • 🗺️ Roadmap
  • 📞 Contact
  • ⚖️ License
  • 📜 Legal Notice

SMSGate Server is the backend of the SMSGate ecosystem. It accepts SMS/MMS dispatch requests through a REST API, routes them to connected Android devices over Firebase Cloud Messaging, and tracks delivery state. It runs in two modes: public (anonymous device registration, used at api.sms-gate.app) and private (token-protected registration, push relayed through the upstream). Deep docs: https://docs.sms-gate.app/.

• Text, data, scheduled SMS and MMS dispatch
• Message status tracking and cancellation
• Message listing with filtering, sorting and limit/offset pagination
• Device management (list, delete, last-seen and SIM card info)
• Health check endpoints (live, ready, startup)
• JWT authentication with scopes and token refresh
• OTP-based device registration
• Inbox and settings APIs
• Public and private deployment modes
• Redis-backed cache and pub/sub for multi-replica deployments
• Prometheus metrics at /metrics
• MySQL 8.0.13+ / MariaDB 10.2.7+ storage (MariaDB LTS recommended)

• MySQL 8.0.13+ or MariaDB 10.2.7+ database (MariaDB LTS recommended)
• Docker + Docker Compose for container setup
• Go 1.26+ for building from source

1. Create configs/config.yml from configs/config.example.yml.
2. For private mode set gateway.mode: private and gateway.private_token.
3. Start the server:

docker run -p 3000:3000 \
  -v ./configs/config.yml:/app/config.yml \
  ghcr.io/android-sms-gateway/server:latest

Or with Compose (backend + background worker + MariaDB):

docker compose -f deployments/docker-compose/docker-compose.yml up --build

The worker handles background tasks: message hashing, message/device/token/inbox cleanup. Run it as a separate process or via the worker subcommand:

./sms-gateway worker

Or with the Helm chart:

helm install sms-gate deployments/helm-chart

Local development:

make run        # go run ./cmd/sms-gateway/main.go
make air        # hot-reload dev server (TZ=UTC DEBUG=1)
make db-upgrade # apply migrations

Configuration lives in configs/config.example.yml; every key can be overridden by env vars using SECTION__KEY (e.g. DATABASE__HOST, GATEWAY__MODE). Key sections: database, gateway, http, fcm, sse, messages, cache, pubsub, jwt, otp, plus tasks (worker only).

export GATEWAY__MODE=private
export GATEWAY__PRIVATE_TOKEN=change-me
export DATABASE__HOST=localhost
export HTTP__LISTEN=0.0.0.0:3000

See configs/config.example.yml for all options and .env.example for every supported environment variable.

The background worker runs periodic tasks controlled by the tasks config section:

The API supports Basic auth and JWT bearer tokens. JWT tokens carry scopes and are issued per user:

• POST /api/3rdparty/v1/auth/token - issue access/refresh pair (Basic auth)
• POST /api/3rdparty/v1/auth/token/refresh - rotate access token (Bearer refresh)
• DELETE /api/3rdparty/v1/auth/token/{jti} - revoke token (Basic auth)

Available scopes: messages:send, messages:list, messages:read, messages:export, messages:cancel, devices:list, devices:delete, inbox:list, inbox:read, inbox:refresh, logs:read, settings:read, settings:write, tokens:manage, tokens:refresh, webhooks:list, webhooks:write, webhooks:delete.

Full reference: integration/authentication.

Also available: root health probes at /health, /health/live, /health/ready and /health/startup, Prometheus metrics at /metrics, and the API catalog at /.well-known/api-catalog.

GET /api/3rdparty/v1/logs is registered but always responds 501 Not Implemented.

Swagger UI is served at /api/docs/index.html (spec at /api/docs/doc.json) when http.openapi.enabled: true. It covers the third-party API; the mobile API is not part of the published schema.

• Private server setup
• API integration
• Authentication
• Webhooks

Open an issue first, then submit a PR. Run make lint and make test locally.

Track planned work and known issues in the issue tracker.

• Email: [email protected]
• Documentation: docs.sms-gate.app
• Issues: github.com/android-sms-gateway/server/issues

Apache-2.0. See LICENSE.

Android is a trademark of Google LLC.