httpSMS: Your Android Phone as an SMS Gateway
Send and receive SMS messages using your Android phone programmatically via a simple HTTP API
At a glance
- What is it?
- httpSMS turns an Android handset into a programmable SMS gateway behind an HTTP API. It is a good fit when virtual numbers are unavailable, but the phone becomes part of your production stack.
- Who is it for?
- Adopt httpSMS if you need programmable SMS in a country where virtual numbers are unavailable and you can keep an Android phone powered and online. Do not adopt it if you need carrier-grade uptime, cannot run a device, or want to avoid the AGPL-3.0 obligations.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- NdoleStudio/httpsms6,339 ★ · +1,166
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| NdoleStudio/httpsms | 5.2k | 6.3k |
1,166 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem httpSMS solves, and who it is for
The README explains the origin directly: the author is from Cameroon and wanted an automated way to send and receive SMS through an API, but many countries do not support buying virtual phone numbers. Existing SMS providers assume you can rent a number in the destination country. httpSMS inverts that. You already own a phone number on an Android handset, and the project makes that handset the sending and receiving endpoint. The audience is developers and small teams who need programmatic SMS in a market where number provisioning is not an option, and who are willing to keep a physical device running. It is not aimed at teams that need a carrier with an SLA, short codes, or a sender identity that survives a lost handset.
How the API, push queue and Android app fit together
The architecture is documented as a sequence. A client calls POST /v1/messages/send on the API. The API does not send anything itself; it schedules a notification about the new message on a push queue and immediately answers the caller with HTTP 202 (Accepted). Later, the queue triggers the API, which sends a push notification to the Android app. The app fetches the message, calls the Android SMS API to send it, then reports the send result and the delivery report back to the API asynchronously. That 202 is the important detail: the HTTP response means the message was accepted for delivery, not delivered. Anything you build on top has to treat the webhook and delivery report as the real completion signal. The API itself is written in Go with Fiber and uses CockroachDB for the database, according to the README, and runs as a serverless application on Google Cloud Run. The Android app is a native Kotlin application. The web interface is Nuxt and Vuetify, hosted as a single page application on Firebase. The repository is split into api/, android/, web/ and tests/ directories, which matches that three-part design.
Installing httpSMS and sending a first message
The README points to https://docs.httpsms.com as the quick start guide. The repository also ships a docker-compose.yml that starts four services: postgres on host port 5435, redis on 6379, the api on 8000, and the web front end on 3000. The api service reads its configuration from ./api/.env, so that file has to exist before the stack will come up. The README's self-host section lists the surrounding steps in order: set up Firebase, set up an SMTP email service, set up Cloudflare Turnstile, download the code, set up the environment variables, build and run, create the system user, then build the Android app. Those external services are not optional decoration; they are part of the setup path the README describes. The compose file itself is the source for the service definitions and ports:
services:
postgres:
image: postgres:alpine
ports:
- "5435:5432"
redis:
image: redis:latest
command: redis-server
ports:
- "6379:6379"
api:
build:
context: ./api
ports:
- "8000:8000"The api container waits for postgres to pass its health check before starting, and depends on redis being started. Once the stack is running, the Android app has to be installed on a phone. The README gives https://apk.httpsms.com/HttpSms.apk as the download and also links the GitHub releases page. Only after the phone is paired can messages flow. On the sending side, the README shows the Go client, which takes an API key from the settings page at https://httpsms.com/settings:
client := htpsms.New(htpsms.WithAPIKey(/* API Key from https://httpsms.com/settings */))
client.Messages.Send(context.Background(), &httpsms.MessageSendParams{
Content: "This is a sample text message",
From: "+18005550199",
To: "+18005550100",
})That snippet is copied from the README with its placeholder numbers. The From value is the number of the Android phone, not a number you buy. The README lists Go and JavaScript/TypeScript clients for the API, and the API documentation is served at https://api.httpsms.com/index.html. After a send call, the caller should expect 202 rather than a delivery confirmation.
Encryption, webhooks, back pressure and message expiration
Four features shape how the system behaves in production. End-to-end encryption uses AES-256, and the README states that the encryption key is stored only on the mobile phone, so the server cannot view message content. That is a real design commitment, and it also means losing the phone or wiping it can mean losing the key. Webhooks forward SMS messages received on the Android phone to a callback URL you provide, which is how you build inbound flows. Back pressure is a rate limit, described in the README with the example of 3 messages per minute, so a call that queues 100 recipients drains at that rate instead of hammering the Android SMS API. Message expiration is the answer to a phone that does not receive the push notification in time: the README says you can set a timeout for which a message is valid, and you are notified when a message expires. Read together, these features admit that the delivery path depends on a device that can be offline, asleep, or out of signal. The rate limit and the expiration timeout are the two knobs that keep that reality from turning into silent failure.
Where httpSMS is the wrong tool
The dependency on a physical Android phone is the limitation that decides most adoptions. If the handset is off, out of coverage, or has its push notifications suppressed by battery optimisation, the message sits until the expiration timeout fires. There is no second path to the carrier, because the carrier relationship belongs to the SIM in that phone. A 202 means the message was accepted, not delivered, so a caller that needs exactly-once semantics has to build its own reconciliation against delivery reports. Self-hosting with the repository's docker-compose.yml means running Postgres, Redis, the API and the web front end yourself, alongside Firebase, an SMTP service, Cloudflare Turnstile and the phone's own SMS plan. Throughput is bounded by the Android SMS API and by the rate limit you configure, so this is not a bulk broadcast tool. Finally, the licence is AGPL-3.0, which matters if you plan to modify the API and offer it to others over a network.
Alternatives and how they differ
The obvious alternative is a conventional SMS API provider where the number is virtual and the carrier relationship belongs to the vendor. That approach removes the phone, the push queue and the Android app from your stack, and it usually comes with delivery guarantees and higher per-message pricing. The difference in approach is where the message originates: with a virtual-number provider, a server talks to a carrier gateway; with httpSMS, a server talks to a phone that talks to a carrier. That makes httpSMS usable in countries where virtual numbers are not sold, which is exactly the gap the README describes, and it makes it a poor fit where virtual numbers are cheap and reliable. A second alternative is building your own Android SMS forwarder with something like Tasker or a custom Kotlin app. That gives you full control and no AGPL obligations, but you would be reimplementing the queue, the rate limit, the expiration handling, the webhook delivery and the pairing flow that httpSMS already ships. The README also lists Go and JavaScript/TypeScript API clients, so if you only need outbound sends from one of those languages, you are choosing between this project and writing the Android side yourself.
Maintenance, upgrade cost and licence
The repository is not archived, and the last push was on 2026-11-01. Recent releases are v1.0.0 on 2026-06-25, v1.1.0 on 2026-07-14 and v1.2.1 on 2026-08-23. That cadence suggests the project is still moving, but the version numbers also mean the API surface is young: a major version bump from 1.x to 2.x would be the moment to read release notes carefully before upgrading. Upgrading the self-hosted stack is not a single container pull. The compose file builds the api and web images from ./api and ./web, so an upgrade means rebuilding both, and the Android app has to be reinstalled or updated on the phone separately because it is distributed as an APK rather than through a store update path the README describes. The database is CockroachDB in the hosted deployment and Postgres in the compose file, which is a divergence worth tracking when you move between the two. On licensing, the project is AGPL-3.0. That licence carries network-copyleft obligations, so if you modify the API and let users interact with it over a network, you should read the licence text and take your own advice on what you must publish. Nothing here is legal advice.
Editorial conclusion
Adopt httpSMS if you need programmable SMS in a country where virtual numbers are unavailable and you can keep an Android phone powered and online. Do not adopt it if you need carrier-grade uptime, cannot run a device, or want to avoid the AGPL-3.0 obligations. Verify first that the Android app is installed and paired, that the API key from the settings page works against /v1/messages/send, and that your webhook endpoint is reachable from the platform.
Frequently asked questions
What is httpSMS?
httpSMS is a service that lets you use your Android phone as an SMS gateway. You call a simple HTTP API and it triggers your Android phone to send an SMS, and messages received on the phone can be forwarded to your webhook endpoint.
How do I use httpSMS?
Install the Android app on a phone, then call the API, for example POST /v1/messages/send, which returns HTTP 202 and schedules a push notification to the phone. The README's quick start guide is at https://docs.httpsms.com.
What are some alternatives to httpSMS?
A conventional SMS API provider with virtual numbers is the main alternative, and it removes the phone from the stack but requires that virtual numbers be available in your country. You could also build your own Android SMS forwarder, which means reimplementing the queue, rate limit, expiration handling and webhook delivery yourself.
Where do I find my SMS messages?
Messages are sent and received on the Android phone, and the README states that received SMS messages can be forwarded to a webhook endpoint you provide.
What is httpSMS used for?
It is used to send and receive SMS messages programmatically through an HTTP API, with the actual sending done by an Android phone. The README describes webhooks for inbound messages and a rate limit to control outbound volume.
Official sources
Where developers are discussing it
Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 0 in the last 30 days; newest first.
- httpSMS: Send and receive SMS messages using your Android phone programmaticallyHacker News · Oct 5, 2026 · 1 points · 0 comments
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/ndolestudio-httpsms)Star history chart for your README
[](https://hysenlabs.com/projects/ndolestudio-httpsms)Was this useful?