Overview

textbee is an open-source SMS gateway that turns an Android phone you own into an SMS API. Your application calls a REST endpoint (or uses the dashboard, the JavaScript SDK, n8n or the MCP server), and the message goes out through the phone's SIM from your own number. These docs cover sending, receiving with webhooks or polling, devices, self-hosting, troubleshooting and the full API reference.

Start with the quickstart to pair a phone and send a first message in about five minutes. Then use the API reference for every endpoint.

How it works

textbee has three parts:

A send goes this way:

1. Your code calls POST /gateway/send-sms with an API key.
2. The API stores the message and sends a push to the phone.
3. The app on the phone hands the message to the carrier.
4. The app reports the status back (sent, delivered or failed).

A receive goes the other way:

1. A person sends an SMS to the phone's number.
2. The app uploads the message to the API.
3. The API sends a MESSAGE_RECEIVED event to your webhook and adds the message to your message history.

Pick your path

Getting started

1. Set up textbee: create your account and install the app.
2. Register a device: connect your Android phone.
3. Create an API key: authenticate your requests.
4. Send your first SMS: call the API.

Documentation structure

• Getting started: account setup, device registration, reconnecting a device and API keys.
• Sending SMS: single and bulk sends, delivery status, choosing a SIM and scheduled messages.
• Receiving SMS: incoming messages, message history and SMS filters on the phone.
• Devices: list your phones, read their health fields and pick a default.
• Webhooks: event subscriptions, event payloads, signatures and retries.
• SDKs: the JavaScript SDK.
• Agents and automation: the MCP server, the agent quickstart and n8n.
• Self-hosting: run the API, the dashboard and the app on your own server.
• Troubleshooting: messages that do not send and phones that go offline.
• Pricing: plans and limits.
• FAQ: common questions.
• API reference: every public endpoint.

Limits

• Android only: textbee needs an Android phone as the gateway. iOS is not supported.
• The phone must stay online: the phone needs an internet connection (Wi-Fi or mobile data) and power. Android can pause background apps, which delays messages. See Keep the phone online.
• Plan limits: each plan has daily, monthly and per-batch message limits and an active device limit. See Pricing.
• SMS only: textbee does not send or receive MMS.
• Phone speed: the phone sends one message at a time, with the Send Delay you set in the app between messages. A large batch takes time to finish.

Reference

• API reference: every public endpoint with parameters, fields, error codes and curl examples
• OpenAPI spec: the same reference as machine-readable OpenAPI 3
• llms-full.txt: all docs and the API reference in one plain-text file

Need help?

• Troubleshooting
• Discord community
• FAQ
• Status page
• support@textbee.dev