---
title: "Send an SMS"
method: POST
path: "/api/v1/gateway/send-sms"
tags: ["gateway"]
---

# Send an SMS

`POST /api/v1/gateway/send-sms`

## Request

- Base URL: `https://api.textbee.dev`
- URL: `https://api.textbee.dev/api/v1/gateway/send-sms`
- Auth: API key in header `x-api-key`

Sends one message to one or more recipients from a phone on your account. deviceId is optional: without it textbee uses your default device, otherwise the enabled device with the most recent heartbeat. Every recipient counts as one message against your plan.

## Request body

- SendSMSRequestDTO
  - `message` string, required: Text of the message. Long messages are split by the carrier.
  - `recipients` string[], required: Phone numbers to send to, in international format. Each recipient is billed as one message.
  - `simSubscriptionId` number: SIM to send from, as subscriptionId from the device simInfo. Defaults to the device default SIM. Android can assign a new id when a SIM is removed and reinserted or swapped, so read the current id from the SIM Cards section of the textbee app before you hard-code it. An id that matches no active SIM is sent from the preferred SIM set in the textbee app, or the device default SIM.
  - `scheduledAt` string: ISO 8601 time to send the message. Must be in the future. Omit to send now.
  - `smsBody` string: Legacy alias for message. Used only when message is absent.
  - `receivers` string[]: Legacy alias for recipients. Used only when recipients is absent.
  - `deviceId` string: Device to send from. When omitted, uses your default device, or the enabled device with the most recent heartbeat.

## Response `200`

The send was accepted. Use smsBatchId to follow delivery. Acceptance is not delivery: the phone still has to be online.

- SendSMSResponseDTO
  - `data` SendSMSResultDTO, required
    - `success` boolean: Whether the batch was accepted. Queued sends only.
    - `message` string: Human readable outcome. Queued sends only.
    - `smsBatchId` string: Batch id. Pass it to GET /gateway/devices/{id}/sms-batch/{smsBatchId} to follow delivery. Queued sends only.
    - `recipientCount` number: Number of recipients in the batch. Queued sends only.
    - `estimatedCompletionAt` string, date-time: Projected time the device finishes sending, based on the recipient count and the device send delay setting. Present only when the batch is large enough to be released in waves. The device must stay online for the estimate to hold.
    - `successCount` number: Messages pushed to the device. Returned instead of the queue fields when the instance dispatches immediately.
    - `failureCount` number: Messages that could not be pushed to the device.
    - `warning` SendSMSWarningDTO
      - `code` string, required: Machine readable warning code. SMS_PERMISSION_MISSING: the textbee app on the sending phone last reported the SMS permission as off. The message is queued, and it fails if the permission is still off.
      - `message` string, required: Human readable explanation of the warning.

## Other responses

- `400`: No enabled device to send from, the device is disabled, your email is not verified, or the message could not be pushed to the phone.
- `401`: Missing, invalid, or revoked API key.
- `429`: Your daily, monthly, or per-batch plan limit is used up. The body says which one.

---

[API](https://skmtc.dev/textbee/apis/textbee-api.md) · [All operations](https://skmtc.dev/textbee/apis/textbee-api/llms.txt) · [OpenAPI document](https://skmtc.dev/textbee/apis/textbee-api/revisions/e720417e9514?raw)