# textbee Review: An Android SMS Gateway You Can Self-Host

> textbee turns an Android phone into an SMS gateway with a REST API, dashboard and MCP server. It is a good fit for low-volume OTP and alert traffic, and the wrong tool for high-throughput or compliance-heavy messaging.

**textbee/textbee** — open-source sms-gateway. turn any android phone into an sms gateway

- Repository: https://github.com/textbee/textbee
- Website: https://textbee.dev
- Stars: 3,125 · Forks: 459
- Language: TypeScript
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/textbee-textbee

## What textbee actually replaces

textbee is an open-source SMS gateway that routes messages through an Android phone you own rather than through a rented number on a messaging API. The README frames the comparison directly: cost per SMS is your carrier plan rather than roughly $0.008+ per message, the phone number is your own SIM, and the whole stack is self-hostable. That last point is the real differentiator for teams that cannot send message content through a third party.

The audience is narrow and specific. Developers who need OTP or 2FA delivery, order and appointment notifications, server and cron alerts, form-to-SMS follow-ups, or bulk announcements to a contact list. The README also lists AI agents as a target, which is why an MCP server exists. This is not a product for a marketing team that needs deliverability analytics and sender reputation management. It is for someone who already has a phone, a SIM and a script.

## How messages leave your phone

The architecture is three parts. An Android app installed on the phone holds the SIM and the SMS permissions. A NestJS API stores devices, messages and API keys in MongoDB. A Next.js web dashboard is the human interface. The Android client registers itself against the backend by scanning a QR code from the dashboard or by entering an API key manually, and it maintains a heartbeat.

Sending is where the design shows. According to the README, a request goes out through your default device, or otherwise the enabled device with the most recent heartbeat. You can override that by passing an optional `deviceId` in the request body. The older `/gateway/devices/{deviceId}/send-sms` route still works but is deprecated. That heartbeat-based routing is the mechanism behind multi-device support: more phones means more throughput, with the API picking one automatically unless you pin a device.

Receiving works differently. Message history is account-level, so one call covers every device and no device id is needed. Incoming messages reach you through the REST API, the dashboard, or webhook notifications to a URL you configure. Enabling SMS receiving in the mobile app is a prerequisite, not an optional setting.

## Installing textbee and sending your first SMS

The hosted path is the shortest. The README's getting started list is: register at textbee.dev, install the app from textbee.dev/download, grant SMS permissions, then click register device or generate an API key in the dashboard and scan the QR code with the app. After that you can send from the dashboard or over the API.

The API call below is the README's own example. It posts to the current send endpoint with an `x-api-key` header and a `recipients` array. A successful call returns without an error, and the message appears in the dashboard's message history for the account.

```bash
curl -X POST "https://api.textbee.dev/api/v1/gateway/send-sms" \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipients": [ "+12025550123" ],
    "message": "Hello World!"
  }'
```

Reading replies uses a GET on the messages endpoint with a direction filter. The README notes this is account-level, so you do not pass a device id.

```bash
curl -X GET "https://api.textbee.dev/api/v1/gateway/messages?direction=received" \
  -H "x-api-key: YOUR_API_KEY"
```

If you want an AI client to drive it, the MCP server is configured in the client's config file. The README's snippet sets `TEXTBEE_API_KEY` in the environment and runs the package through npx. It exposes three tools: `send_sms`, `get_messages` and `list_devices`. Self-hosted instances are pointed at with `TEXTBEE_BASE_URL`.

```json
{
  "mcpServers": {
    "textbee": {
      "command": "npx",
      "args": ["-y", "@textbee/mcp"],
      "env": { "TEXTBEE_API_KEY": "YOUR_API_KEY" }
    }
  }
}
```

Self-hosting is a different exercise. The README lists the stack as React, Next.js, Node.js, NestJS, MongoDB, and an Android app in Kotlin with Jetpack Compose plus legacy Java. It instructs you to install MongoDB or use MongoDB Atlas, create a Firebase project with Cloud Messaging enabled, and obtain Firebase credentials for both the backend and the Android app. The repository ships a `docker-compose.yaml` with a `textbee-db` MongoDB service, an optional `mongo-express` admin UI, a `textbee-api` NestJS service, and a `textbee-web` Next.js service. The database service maps host port `${MONGO_PORT:-27018}` to container port 27017, and the API maps `${PORT:-3001}` to 3001. Note that the compose file expects an `./api/.env` file via `env_file`, so the stack will not start without one. The README text available here is truncated inside the Android build section, so treat the app build steps as something to read in full on the repository before you start.

## The phone is the gateway, and that is the constraint

Everything about textbee inherits the limits of a consumer SIM. The README is direct about this: the phone must be powered on, running the app, and connected to the internet. A spare Android phone on a charger is the intended deployment. That means your SMS pipeline has a physical dependency that a hosted API does not, and a dead battery, a dropped Wi-Fi connection, or an Android battery-optimization setting that kills the background service all become production incidents.

Carrier policy is the second limit. The FAQ states that carriers apply their own rate limits and anti-spam policies, which vary by country and plan, and that you are responsible for staying within your carrier's terms. For higher throughput the README suggests multiple devices and SIMs plus reasonable sending rates. There is no queueing guarantee, no delivery receipt SLA, and no documented fallback if every device is offline. The FAQ also points out that SMS marketing is regulated in most countries, naming TCPA in the US and GDPR/ePrivacy in the EU, and that textbee is a tool rather than a compliance layer.

If your use case needs guaranteed delivery windows, audited sender reputation, or volumes that would trip carrier anti-spam thresholds, this is the wrong tool. The same applies if nobody on the team can physically own the phone.

## textbee against Twilio and self-hosted SMS servers

The obvious alternative is Twilio and similar messaging APIs, and the README's own table spells out the trade. Twilio rents you a number, charges per message, handles carrier relationships and compliance paperwork, and gives you delivery infrastructure you do not operate. textbee gives you none of that: you bring the number, you pay your carrier, and you run the gateway. The difference is not price alone. It is who owns the failure. With Twilio, a failed send is a support ticket. With textbee, it is a phone that went to sleep.

The other comparison is the Android SMS gateway category itself, which the related searches surface as a group. Several projects in that space put a small HTTP server directly on the phone, so your application talks to the device on your local network. textbee inverts that: the phone is a client that registers with a central backend, which owns the API keys, message history, webhooks, bulk CSV sending and multi-device routing. That is a better fit for cloud applications and for agents, and a worse fit if you wanted to avoid running a server at all. If your only requirement is a script on the same LAN sending a text, a phone-local gateway is less machinery. If you want an API key, a dashboard and webhook callbacks, textbee's central model is the more useful shape.

## Maintenance, licence and what a year of textbee costs

The repository is not archived, and the last push was on 2026-09-21, three days before this writing. That is a live project. Releases are spaced rather than constant: v2.7.1 in March 2026, v2.8.0 in June 2026, v2.9.0 in September 2026. Roughly quarterly. Plan your upgrade cadence around that, not around continuous delivery.

Upgrade cost depends on which half you run. The hosted service upgrades itself. A self-hosted deployment means pulling new images or rebuilding `api/` and `web/`, and the compose file's commented-out `ghcr.io/textbee/textbee/api:latest` and `ghcr.io/textbee/textbee/web:latest` lines show that prebuilt images exist as an alternative to building from source. The Android app is the awkward part: it is installed on a physical device, so an update is a manual action on a phone you may not be holding. If the API changes a contract the app depends on, you have a version-skew problem across a device you cannot script.

Licence is MIT. In plain terms, that permits commercial use, modification and redistribution with the licence notice preserved. It does not give you a warranty, and it does not shift responsibility for carrier terms or messaging law to the maintainers. The README states plainly that you are responsible for consent and for complying with applicable regulations. That is a statement about your obligations, not a legal opinion about your situation.

## Conclusion

Adopt textbee if you send low to moderate volumes from your own SIM and want API access without per-message billing, and if you can keep a dedicated Android phone powered on and online. Do not adopt it for high-volume marketing, strict delivery SLAs, or anywhere a carrier policy violation would be business-critical. Before committing, verify three things on your own carrier: whether your plan allows application-driven sending, what its daily message cap is, and whether receiving SMS is enabled in the app, since the README states receiving must be turned on before incoming messages appear in the API.

## FAQ

### Can I use my Android phone as an SMS gateway with textbee?

Yes. That is the core design: you install the Android app, grant SMS permissions, register the device from the dashboard by scanning a QR code or entering an API key, and messages then send through your own SIM. The README notes the phone must stay powered on, running the app, and connected to the internet.

### Is textbee free?

The project is open source under MIT and can be self-hosted, so there is no per-message fee from textbee itself; you pay your carrier plan. The README also points to textbee.dev for current plans and limits on the cloud-hosted version.

### How do I use textbee?

Register at textbee.dev, install the Android app from textbee.dev/download, grant SMS permissions, then register a device or generate an API key in the dashboard and scan the QR code with the app. After that you can send from the dashboard or call the REST API with an x-api-key header.

### What is textbee.dev?

It is the project's website and the home of the hosted version of the gateway, where you register an account, download the Android app, and manage devices and API keys from a dashboard. The README also links to textbee.dev/docs for the API and MCP documentation.

### What is a textbee alternative?

The README compares textbee with Twilio and similar APIs: those rent you a number and charge per message, while textbee sends through your own SIM and can be self-hosted. The choice comes down to whether you want to operate the gateway yourself.

## Sources

- [License: MIT](https://github.com/textbee/textbee/blob/main/LICENSE)
- [Project website](https://textbee.dev)
- [README](https://github.com/textbee/textbee/blob/main/README.md)
- [Releases](https://github.com/textbee/textbee/releases)
- [textbee/textbee on GitHub](https://github.com/textbee/textbee)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/textbee-textbee