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

Payload Respons

data

array of object

wajib

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

Tampilkan atribut turunan

data.id

string

wajib

Message ID.

data.direction

string

wajib

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

data.status

object

wajib

data.to

string

wajib

Recipient phone number in E.164 format.

data.from

string

wajib

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

data.text

string

wajib

Message body.

data.category

nullable string

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

data.segments

object

wajib

Segment breakdown for the body.

Tampilkan atribut turunan

data.segments.count

integer

wajib

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

data.segments.encoding

string

wajib

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

wajib

Character count of the body under the selected encoding.

data.cost

nullable object

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

Tampilkan atribut turunan

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

wajib

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.

Tampilkan atribut turunan

data.cost.breakdown.per_segment

string

wajib

Per-segment price as a decimal string.

data.cost.breakdown.segments

integer

wajib

Number of billable segments.

data.cost.breakdown.country_code

string

wajib

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

data.cost.breakdown.carrier_surcharge

string

wajib

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.

Tampilkan atribut turunan

data.tags.name

string

wajib

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

data.tags.value

string

wajib

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.

Tampilkan atribut turunan

data.last_error.code

string

wajib

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

wajib

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

wajib

When the failure occurred.

data.created_at

string

wajib

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

wajib

Aggregate result for the batch.

Tampilkan atribut turunan

summary.accepted_count

integer

wajib

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"
    }
  ]'