Send a batch of SMS messages

POST

/v1/sms/batches

curl -X POST "https://us1.platform.bird.com/v1/sms/batches" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "to": "+15551111111",
      "from": "+15557654321",
      "text": "Hi Alice!",
      "category": "marketing"
    },
    {
      "to": "+15552222222",
      "from": "+15557654321",
      "text": "Hi Bob!",
      "category": "marketing"
    }
  ]'

Accepts up to 100 independent SMS messages and queues them for delivery. Each message is an independent send with its own ID, status, and cost. All items are validated before any are queued — if one fails validation, the entire batch is rejected. Field-level validation failures, the 12-segment body cap, and insufficient workspace balance all return 422 (or 402 for balance).

Response Payload

data

array of object

आवश्यक

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

चाइल्ड एट्रिब्यूट दिखाएँ

data.id

string

आवश्यक

Message ID.

data.direction

string

आवश्यक

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

data.status

object

आवश्यक

data.to

string

आवश्यक

Recipient phone number in E.164 format.

data.from

string

आवश्यक

Sender the message was sent from — an E.164 number, an alphanumeric sender ID, or a short code.

data.text

string

आवश्यक

Message body.

data.category

nullable string

Content classification supplied on the send. Null for inbound messages.

data.segments

object

आवश्यक

Segment breakdown for the body.

चाइल्ड एट्रिब्यूट दिखाएँ

data.segments.count

integer

आवश्यक

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

data.segments.encoding

string

आवश्यक

Encoding used for the body. GSM_7BIT fits 160 characters in a single segment (153 per part when multi-segment); UCS2 is used when the body contains any character outside the GSM 03.38 alphabet (emoji, CJK, some accented characters) and fits 70 characters in a single segment (67 per part when multi-segment).

data.segments.characters

integer

आवश्यक

Character count of the body under the selected encoding.

data.cost

nullable object

Cost of the message. Null until the message has been priced.

चाइल्ड एट्रिब्यूट दिखाएँ

data.cost.currency_code

string

ISO 4217 currency code for the cost amount. Omitted when the cost is not denominated in a currency (for example a zero-priced internal send).

data.cost.amount

string

आवश्यक

Total cost as a decimal string — the per-segment rate multiplied by the segment count, plus any surcharges.

data.cost.breakdown

object

Per-component cost breakdown. Returned on single-message reads; omitted from list rows.

चाइल्ड एट्रिब्यूट दिखाएँ

data.cost.breakdown.per_segment

string

आवश्यक

Per-segment price as a decimal string.

data.cost.breakdown.segments

integer

आवश्यक

Number of billable segments.

data.cost.breakdown.country_code

string

आवश्यक

ISO 3166-1 alpha-2 destination country the price was resolved for.

data.cost.breakdown.carrier_surcharge

string

आवश्यक

Carrier surcharge component as a decimal string (for example US 10DLC fees). 0.0000 when none applies.

data.tags

array of object

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

चाइल्ड एट्रिब्यूट दिखाएँ

data.tags.name

string

आवश्यक

Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.

data.tags.value

string

आवश्यक

Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.

data.metadata

object

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

data.validity_period

integer

How long, in seconds, Bird keeps trying to deliver before the message transitions to expired.

data.carrier

nullable string

Carrier that handled the message, when known. Populated once a delivery receipt identifies it.

data.mcc_mnc

nullable string

Mobile country code and mobile network code of the carrier, when known.

data.last_error

nullable object

Failure detail on a terminally failed or rejected message. Null otherwise.

चाइल्ड एट्रिब्यूट दिखाएँ

data.last_error.code

string

आवश्यक

Bird-stable failure reason. invalid_destination — the number is not assigned, ported out, or malformed. unreachable — handset off or out of coverage. blocked_by_carrier — the carrier filtered the message. blocked_by_recipient — the recipient device blocked the sender. landline_unreachable — the destination is a landline that does not accept SMS. content_rejected — the carrier rejected the content. sender_unregistered — the sender is not registered for the destination. recipient_opted_out — the recipient is on a suppression list. provider_unavailable — an upstream failure after retries. unknown — an unmapped failure.

data.last_error.description

string

आवश्यक

Human-readable explanation of the failure.

data.last_error.carrier_error_code

nullable string

Raw carrier-supplied error code, when available, for low-level debugging.

data.last_error.occurred_at

string

आवश्यक

When the failure occurred.

data.created_at

string

आवश्यक

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

आवश्यक

Aggregate result for the batch.

चाइल्ड एट्रिब्यूट दिखाएँ

summary.accepted_count

integer

आवश्यक

Number of messages accepted in the batch.

curl -X POST "https://us1.platform.bird.com/v1/sms/batches" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "to": "+15551111111",
      "from": "+15557654321",
      "text": "Hi Alice!",
      "category": "marketing"
    },
    {
      "to": "+15552222222",
      "from": "+15557654321",
      "text": "Hi Bob!",
      "category": "marketing"
    }
  ]'