Sending SMS

Send SMS through your Android phone with the textbee API: single sends, bulk sends, scheduled sends, SIM choice and delivery tracking.

Updated September 28, 2026

textbee sends SMS from an Android phone that you registered to your account. Your code calls the API, textbee pushes the message to the phone, and the phone sends it through its SIM. This section covers every way to send and how to follow a message to the recipient.

Send one message

This request sends one message from your default device:

Shell

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": ["+12015550123"], "message": "Your order has shipped"}'

The response has an smsBatchId. Keep it to follow delivery. Sending SMS has every request field, the status codes and samples in five languages.

Ways to send

Goal	How	Page
Send the same text to one or more numbers	`POST /gateway/send-sms` with a `recipients` array	Sending SMS
Send different texts to different numbers in one call	`POST /gateway/send-bulk-sms` with a `messages` array	Sending bulk SMS
Send a personalized message to each row of a spreadsheet	CSV upload in the dashboard	Sending bulk SMS
Send at a later time	`scheduledAt` on the request	Schedule a message
Send from a specific SIM on a dual-SIM phone	`simSubscriptionId` on the request	Send from a specific SIM
Send from a specific phone	`deviceId` on the request	Devices

Choose the phone

A request without deviceId goes out from your default device. If you have no default, textbee uses the enabled device with the most recent heartbeat. Pass deviceId to pick a phone yourself. Registering a device explains how to set the default.

Follow the message

A 200 response means textbee accepted the message. It does not mean the recipient got it. After the response, the message moves through these states:

pending and dispatched: textbee has the message and pushes it to the phone.
sent: the phone handed it to the carrier, and the carrier accepted it.
delivered: the carrier reported that the recipient's handset got it.

A message can also end as failed. Some carriers never send a delivery report, so delivered does not always arrive. Delivery status and message states explains every state and its timestamps.

You can follow messages in three ways:

Webhooks. textbee calls your URL when a message is sent, delivered or failed. See Webhook events.
The batch endpoint. GET /gateway/devices/{id}/sms-batch/{smsBatchId} returns the batch and each message in it.
Message history. GET /gateway/messages?smsBatchId=...&status=failed lists the recipients that failed. See Message history.

Limits

Each recipient counts as one message against your plan. Your plan's daily, monthly and per-batch limits apply to every send. When a send goes over a limit, the API returns 429 and sends nothing. The pricing page lists the limits for each plan.

The phone also sets a pace. The Send Delay setting in the app puts a gap between messages in a batch, so a large batch takes time to finish. Sending bulk SMS explains the setting.

Before you send

Verify your email. Sends fail with 400 until you do.
Register at least one phone and keep it online. See Keep the phone online.
Create an API key. See API keys and authentication.
Write phone numbers in E.164 format, for example +12015550123.