---
title: "Send several SMS in one call"
method: POST
path: "/api/v1/gateway/send-bulk-sms"
tags: ["gateway"]
---

# Send several SMS in one call

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

## Request

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

Sends a batch where every entry has its own text and recipients. deviceId is optional and resolves the same way as POST /gateway/send-sms.

## Request body

- SendBulkSMSRequestDTO
  - `messageTemplate` string: Optional label for the batch. Each entry in messages carries its own text.
  - `messages` SMSData[], required: Messages to send. Every message can target different recipients and use a different SIM.
    - `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 batch was accepted.

- 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 batch 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)