The Problem
Applications that need to send or receive SMS typically depend on paid gateway services or physical GSM modems. This project turns an Android smartphone into a self-hosted SMS gateway, exposing a REST API for sending messages and delivering incoming SMS/MMS as webhooks. It removes the need for a third-party SMS provider when you already have a device with a SIM card.
What This Does
The app is a Kotlin/Android application that runs a local HTTP server (app/src/main/java/me/capcom/smsgateway/modules/localserver/LocalServerService.kt) with JWT-based authentication (JwtService.kt). It exposes routes for sending messages, reading the inbox, fetching logs, and managing settings (see modules/localserver/routes/). Incoming SMS and MMS are captured via broadcast receivers and content observers (modules/receiver/), then forwarded to configurable webhooks or a cloud relay.
A cloud mode lets the device poll a remote server for outbound messages and push status updates (modules/gateway/workers/), which is useful when the device is behind NAT or carrier restrictions. The app also includes a health-check endpoint, ping service, and an in-app SQLite database for message history and webhook queues.
How To Use It
Setup: Build the APK with Gradle (app/build.gradle is the only build file). The repo includes GitHub Actions workflows for CI builds (build-apk.yml, release-build.yml), so building from source is the primary path. There is no published APK in the repo.
Configuration: The app stores settings via Android preferences (PreferencesStorage.kt). There are no environment variables. Local mode requires no account; cloud mode requires a server URL and registration token configured through the app UI. API authentication uses tokens created in-app.
Running it: Install the APK on an Android 5.0+ device, grant SMS permissions, and start the local server from the app UI. The API is then available at http://<device-ip>:8080 (port configurable). Swagger documentation is bundled at app/src/main/assets/api/index.html.
No CLI commands exist in this repo. Build and install via Android Studio or Gradle, then configure the app through its UI.
The README documents the API and webhook setup but does not specify exact build commands, so I cannot provide verbatim Gradle invocations.
Real-World Use
A small business could run this on a spare Android phone with a prepaid SIM. A backend service sends an SMS by POSTing to http://<device-ip>:8080/messages with a bearer token. Incoming customer replies trigger a webhook to the backend, which routes the message to a support ticket system. The phone sits on a charger with battery monitoring enabled; the health endpoint alerts the backend if the device goes offline.
Code Health & Issues
Med - No dependency lockfile - app/build.gradle declares dependencies without a lockfile, so builds are not reproducible across time. Gradle version catalogs could mitigate this. Med - Only 2 test files - ExampleInstrumentedTest.kt is a placeholder. Core logic (message routing, JWT, webhooks) has no unit tests. Low - 18 database schema migrations - app/schemas/ shows frequent schema changes. This is normal for an active app but increases regression risk without migration tests. Low - Heavily modularized - 25+ modules under modules/ with a service orchestrator (OrchestratorService.kt). Good separation of concerns, but the event bus pattern (EventBus.kt) makes control flow harder to trace. Low - No license issue - Apache 2.0 license is present in the README and LICENSE file.
The Bottom Line
This is a functional, well-structured Android SMS gateway with a clean modular architecture and real-world deployment paths (local and cloud). It is a fork of a 5,300-star project, so the core is proven. The main weaknesses are minimal test coverage and no dependency locking. It is best suited for developers who need a self-hosted SMS API and can tolerate managing an Android device as infrastructure.