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

Treść odpowiedzi

data

array of object

wymagane

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

Pokaż atrybuty podrzędne

data.id

string

wymagane

Message ID.

data.direction

string

wymagane

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

data.status

object

wymagane

data.to

string

wymagane

Recipient phone number in E.164 format.

data.from

string

wymagane

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

data.text

string

wymagane

Message body.

data.category

nullable string

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

data.segments

object

wymagane

Segment breakdown for the body.

Pokaż atrybuty podrzędne

data.segments.count

integer

wymagane

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

data.segments.encoding

string

wymagane

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

wymagane

Character count of the body under the selected encoding.

data.cost

nullable object

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

Pokaż atrybuty podrzędne

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

wymagane

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.

Pokaż atrybuty podrzędne

data.cost.breakdown.per_segment

string

wymagane

Per-segment price as a decimal string.

data.cost.breakdown.segments

integer

wymagane

Number of billable segments.

data.cost.breakdown.country_code

string

wymagane

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

data.cost.breakdown.carrier_surcharge

string

wymagane

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.

Pokaż atrybuty podrzędne

data.tags.name

string

wymagane

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

data.tags.value

string

wymagane

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.

Pokaż atrybuty podrzędne

data.last_error.code

string

wymagane

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

wymagane

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

wymagane

When the failure occurred.

data.created_at

string

wymagane

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

wymagane

Aggregate result for the batch.

Pokaż atrybuty podrzędne

summary.accepted_count

integer

wymagane

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