📱 SMSGate Server

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

📚 Table of Contents

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

📖 About

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

⭐ Features

• Text, data, scheduled SMS and MMS dispatch
• Message status tracking and cancellation
• Device management (list, delete, online state)
• Health check endpoints (live, ready, startup)
• JWT authentication with scopes and token refresh
• OTP-based device registration
• Inbox, settings, and logs APIs
• Public and private deployment modes
• MySQL 8.0.13+ / MariaDB 10.2.7+ storage (MariaDB LTS recommended)

📦 Prerequisites

• 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

🚀 Quickstart

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

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, tasks.

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.

Worker Tasks

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

Task	Default Interval	Purpose
messages_hashing	168h (7 days)	Hash processed messages to avoid plain text storage
messages_cleanup	24h	Delete messages older than max_age (default 720h / 30 days)
devices_cleanup	24h	Remove inactive devices older than max_age (default 8760h / 1 year)
tokens_cleanup	24h	Revoke expired tokens past max_age grace (default 1h)

🔐 Authentication

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:refresh, logs:read, settings:read, settings:write, tokens:manage, tokens:refresh, webhooks:list, webhooks:write, webhooks:delete.

Full reference: integration/authentication.

🔌 API Overview

Group	Base path
Messages	/api/3rdparty/v1/messages
Devices	/api/3rdparty/v1/devices
Webhooks	/api/3rdparty/v1/webhooks
Health	/api/3rdparty/v1/health[/live | /ready | /startup]
Auth	/api/3rdparty/v1/auth/token

Also: /api/3rdparty/v1/inbox, /settings, /logs. OpenAPI schema is served when http.openapi.enabled: true.

📚 Documentation

• Private server setup
• API integration
• Authentication
• Webhooks

🤝 Contributing

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

🗺️ Roadmap

Track planned work and known issues in the issue tracker.

📞 Contact

• Email: support@sms-gate.app
• Documentation: docs.sms-gate.app
• Issues: github.com/android-sms-gateway/server/issues

⚖️ License

Apache-2.0. See LICENSE.

📜 Legal Notice

Android is a trademark of Google LLC.