Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Create a batch of SMS messages

POST
/v1/sms/batches
const result = await bird.sms.sendBatch({
  messages: [
    {
      from: "+15557654321",
      to: "+15551111111",
      text: "Hi Alice!",
      category: "marketing",
    },
    {
      from: "+15557654321",
      to: "+15552222222",
      text: "Hi Bob!",
      category: "marketing",
    },
  ],
});
Response202
{
  "data": [
    {
      "id": "sms_01krdgeqcxet5s7t44vh8rt9mg",
      "direction": "outbound",
      "status": "scheduled",
      "to": "+15551234567",
      "from": "+15557654321",
      "text": "Your order has shipped and is on its way.",
      "category": "transactional",
      "requested_language": "pt-BR",
      "resolved_language": "pt-BR",
      "template_id": "smt_01krdgeqcxet5s7t44vh8rt9mg",
      "template_version_id": "smv_01krdgeqcxet5s7t44vh8rt9mg",
      "template_content_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "segments": {
        "count": 1,
        "encoding": "GSM_7BIT",
        "characters": 41
      },
      "cost": {
        "amount": "0.00990",
        "currency_code": "USD",
        "transaction_amount": "0.00790",
        "passthrough_amount": "0.00200"
      },
      "tags": [
        {
          "name": "category",
          "value": "welcome"
        }
      ],
      "options": {
        "smart_encoding": true
      },
      "carrier": "Verizon",
      "mcc_mnc": "311480",
      "last_error": {
        "code": "invalid_destination",
        "description": "Carrier filtered as spam"
      },
      "created_at": "2026-05-21T12:00:00Z"
    }
  ],
  "summary": {
    "accepted_count": 2
  }
}

Sends up to 100 independent SMS messages in one request. Each item is a complete send request with its own recipient, content, ID, status, and cost. For a single message, use Send an SMS message instead.

Acceptance is all-or-nothing: every item is validated before any is queued, and one invalid item rejects the whole batch with a 422 (nothing is sent). A batch from a workspace with no wallet balance fails with a 402. The 202 response lists the accepted messages in submission order; each delivers asynchronously and is tracked individually, like a single send.

Request Payload

messages
array
required

SMS message send requests, up to 100. Each is an independent send; all are validated before any is queued.

Show child parameters

Response Payload

data
array of object
required

One entry per message in the batch, in submission order.

Show child attributes
data.id
string
required

ID of the message, assigned when the send is accepted. Pass it as message_id to the get-message endpoint.

data.direction
string
required

Whether the message was sent from a Bird sender (outbound) or received from a subscriber (inbound).

Possible values: outbound, inbound

data.status
string
required

Delivery status:

  • accepted: Accepted and awaiting carrier handoff.
  • sent: Handed to the carrier and awaiting a delivery receipt.
  • delivered: Confirmed as delivered.
  • undelivered: The carrier reported delivery as failed for a reason that may clear later, such as a handset out of coverage or a carrier at capacity. Final all the same: the message is not retried, so reaching the recipient means sending again.
  • failed: The carrier reported delivery as failed for a reason that will not clear, such as an unassigned number, a recipient who has opted out, or content the carrier refused.
  • rejected: Refused before carrier handoff.
  • expired: Reached its validity limit without a final receipt.
  • received: Received as an inbound message.

scheduled and canceled are declared ahead of the send-later scheduling feature that produces them, so their arrival is not a breaking change. No message carries either status today.

Possible values: scheduled, accepted, sent, delivered, undelivered, failed, rejected, canceled, expired, received

data.to
string
required

Where the message went. On an outbound message this is the recipient's phone number in E.164 format; on an inbound one it is your own number that received it.

data.from
string
required

Where the message came from. On an outbound message this is the sender you sent it from: an E.164 number, an alphanumeric sender ID, or a short code. On an inbound message, this is the phone number that sent it to you.

data.text
string

The message body. Every message carries body text, attachments, or both, so this is absent only on a received message that carried attachments and no text. For a template send, this is the rendered text after parameter substitution. When category is authentication (a message carrying a one-time code), this is **REDACTED**: the code still reaches the recipient, but the API does not retain it for later reads.

data.category
nullable string

Content classification supplied for free text or derived from the template. Null for inbound messages.

data.requested_language
nullable string
required

The template language requested by the send, in canonical form. Null when the send named no language or used no template.

data.resolved_language
nullable string
required

The template language whose text was rendered, in canonical form. Null when the send used no template. This can differ from requested_language when the template's fallback policy selects another language.

data.template_id
nullable string
required

The template rendered for this message, or null for a free-text message.

data.template_version_id
nullable string
required

The workspace published version or synthetic built-in version rendered at acceptance, or null for a free-text message. For a built-in template, template_content_hash identifies the exact catalogue source.

data.template_content_hash
nullable string
required

The rendered language's source fingerprint, or null for a free-text message.

data.segments
object
required

Segment breakdown for the body.

Show child attributes
data.segments.count
integer
required

Number of segments the body is split into. Each segment is a billable unit.

data.segments.encoding
string
required

Encoding used for the body. The GSM_7BIT encoding fits 160 septets (seven-bit units) in one segment, or 153 per part in a multi-segment message. The UCS2 encoding applies when the body contains a character outside the GSM 03.38 alphabet, including emoji, CJK, and some accented characters. It fits 70 UTF-16 code units in one segment, or 67 per part.

Neither limit counts characters, and both alphabets have characters that cost two units. Under GSM_7BIT there are ten such entries, and they are the whole set: ^, {, }, \, [, ], ~, |, €, and the form feed control. Eighty of those fill a single segment. Under UCS2 an emoji outside the Basic Multilingual Plane is a surrogate pair costing two code units, so 35 of those fill a single segment.

Possible values: GSM_7BIT, UCS2

data.segments.characters
integer
required

Character count of the body, counted in Unicode code points under either encoding. This is not the segment measure: a GSM_7BIT extended-table character counts once here but costs two septets, and a UCS2 emoji outside the Basic Multilingual Plane counts once here but costs two of the segment's 70 code units.

data.cost
nullable object

What the message cost, split into Bird's charge and any third-party fees passed through. Null until the message has been priced.

Show child attributes
data.tags
array of object

Structured {name, value} filter labels applied to this message.

Show child attributes
data.metadata
object

Arbitrary JSON metadata stored on the message and echoed in webhook payloads.

data.options
object

The settings applied to this message, with any option you omitted filled in with the default in force when you sent it. Absent on inbound messages, and on any outbound message for which no settings were recorded.

Show child attributes
data.validity_period
integer

Preview feature: how long, in seconds, the carrier may keep attempting delivery before the message is marked expired. Not returned yet.

data.carrier
string

Carrier that handled the message. Absent until a delivery receipt identifies it, and on a received message the carrier reports it only where a carrier fee applies.

data.mcc_mnc
string

Mobile country code and mobile network code of the carrier. Absent until the carrier is identified.

data.last_error
nullable object

Failure detail on a message that failed, was rejected, was not delivered, or expired. Absent otherwise.

Show child attributes
data.created_at
string
required

When the message was accepted (outbound) or received (inbound).

data.sent_at
nullable string

When the message was handed to the carrier. Null until then.

data.delivered_at
nullable string

When delivery was confirmed. Null until then.

summary
object
required

Aggregate result for the batch.

Show child attributes

Related resources

Continue with the documentation, guides and examples for this topic.

Try the practice and get an implementation brief