--- title: "Create a batch of SMS messages" canonical: "https://bird.com/docs/api/reference/create-sms-message-batch" --- # Create a batch of SMS messages `POST /v1/sms/batches` 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](/docs/api/reference/create-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. ## Code samples **TypeScript** ```ts 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", }, ], }); ``` Examples: [TypeScript](/docs/api/reference/create-sms-message-batch.ts.md) · [Python](/docs/api/reference/create-sms-message-batch.py.md) · [Go](/docs/api/reference/create-sms-message-batch.go.md) · [PHP](/docs/api/reference/create-sms-message-batch.php.md) · [MCP](/docs/api/reference/create-sms-message-batch.mcp.md) · [cURL](/docs/api/reference/create-sms-message-batch.curl.md) ## Example response `202` ```json { "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 } } ``` ## Request body - `messages` (array, required): SMS message send requests, up to 100. Each is an independent send; all are validated before any is queued. - `messages.to` (string, required): Recipient phone number in E.164 format (for example `+14155550100`). One recipient per message. The number is stored and returned in canonical E.164; a recipient that cannot be routed returns a `422` `SMSInvalidRecipient`. - `messages.from` (string): Sender to send from. It must be a sender the workspace holds: a number it owns in E.164, such as `+15557654321`, a short code it holds, such as `24680`, or an alphanumeric sender ID it has claimed, such as `MyBrand`. A sender the workspace does not hold returns a `422` `SMSSenderNotConfigured`, and an alphanumeric sender must also be permitted, and where required registered, for the destination country. Required on a free-text send and when sending a workspace template. Omitting it in either case returns `422`. A built-in template selects its sender automatically and rejects `from`. - `messages.category` (string): Content classification: why you are sending. Required on a free-text send; omit it on a template send, where the category is derived from the template. Where the destination country requires the sender to be registered, a category outside what that registration covers returns a `422` `SenderCategoryNotPermitted`. - `messages.validity_period` (integer): Preview feature: how long, in seconds (60-172800), the carrier may keep attempting delivery before the message is marked `expired`. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. - `messages.tags` (array of object): Structured `{name, value}` labels for filtering and analytics. Tags become first-class query dimensions: filter the list endpoint by tag name, slice analytics by tag, and surface in webhook payloads. Maximum 20 tags per send. Use tags for low-cardinality dimensions (`category`, `experiment_variant`). For arbitrary structured context you do not need as a filter dimension, use `metadata` instead. - `messages.tags.name` (string, required): Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters. - `messages.tags.value` (string, required): Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters. - `messages.metadata` (object): Arbitrary JSON object stored on the message, returned on API reads, and echoed in webhook payloads. Maximum 2 KB serialized. Use metadata for per-send context like internal IDs and foreign keys. For low-cardinality filterable labels, use `tags` instead. - `messages.options` (object): What Bird does to this message on its way out, such as `smart_encoding`. The message being relayed stays at the top level: its recipient, sender, content, and the delivery instructions the carrier acts on. - `messages.options.smart_encoding` (boolean) Replace characters outside the GSM-7 alphabet with their closest GSM-7 equivalent before sending: typically curly quotes, dashes, ellipses, fullwidth forms, and non-breaking spaces. One such character forces the whole body into `UCS2`, which more than halves the characters that fit in a segment, so replacing them often lowers the segment count and the cost. Disabled by default, because it alters the body you composed. The replacement is all-or-nothing: a body that still holds a character outside the alphabet afterwards, such as an emoji or a non-Latin script, is sent exactly as you supplied it. Read the message back to see what was applied: `text` is the body as sent. - `messages.options.track_clicks` (boolean): Preview feature: link click tracking. Defaults to `false`. Currently unavailable; setting this to `true` returns `422 SMSUnsupportedFeature`. - `messages.options.max_price_per_segment` (number): Preview feature: per-segment price ceiling. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. - `messages.media_urls` (array of string): Preview feature: multimedia (MMS) attachments. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. - `messages.messaging_profile_id` (string): Preview feature: sender selection from a messaging profile pool. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. - `messages.scheduled_at` (string): Preview feature: send-later scheduling. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. - `messages.broadcast_id` (string): Preview feature: broadcast correlation. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. - `messages.campaign_id` (string): Preview feature: campaign correlation for analytics. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. - `messages.audience_id` (string): Preview feature: audience-targeted sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. - `messages.contact_id` (string): Preview feature: contact-targeted sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. - `messages.topic_id` (string): Preview feature: topic-gated sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. - `messages.personalization` (object): Preview feature: per-recipient substitution for batch sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. - Variant `text` - `messages.text` (string, required): Free-text message body. Required unless `template` is supplied (the two are mutually exclusive). At least 1 character, up to a 12-segment cap (roughly 1836 GSM-7 or 804 UCS-2 characters). Bird does not truncate; a body exceeding 12 segments is rejected with a 422. The cap applies to segments because GSM-7 and UCS-2 encodings differ in characters per segment. - Variant `template` - `messages.template` (object, required): Send using a stored template instead of free text. The category is derived from the template, so `category` and `media_urls` are rejected. A workspace template requires `from`; a built-in template selects its sender and rejects `from`. - `messages.template.language` (string): Which of the template's languages to send. Omit it to send the template's default language, unless the template sets `language_source_required`, in which case a send naming no language is rejected. When the template does not carry the language you ask for, its own `on_missing_language` setting decides whether the closest available language is sent instead or the send is rejected. - `messages.template.parameters` (object): Values for the template's variables, keyed by variable name. Read the live version to see the accepted keys and formats. A missing key, an undeclared key, an invalid value, or a serialized object over 16 KiB returns `422`. - Variant `id` - `messages.template.id` (string, required): The workspace or built-in template to send, by ID. - Variant `slug` - `messages.template.slug` (string, required): The workspace or built-in template to send, by its immutable slug. Read the template's live version to see its variables. - Variant `name` - `messages.template.name` (string, required): Deprecated. Use `slug` instead. This resolves legacy built-in catalogue names and never matches a workspace template's display name. ## Response body - `data` (array of object, required): One entry per message in the batch, in submission order. - `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) - `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. - `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. - `data.cost.amount` (string, required): Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge. - `data.cost.currency_code` (string, required): ISO 4217 currency code. Every component is denominated in this currency. - `data.cost.transaction_amount` (nullable string, required): What we charged to carry the message, as a decimal string. `null` when this component was not priced; `"0.00000"` when it priced at zero. - `data.cost.passthrough_amount` (nullable string, required): Third-party fees we pass on, as a decimal string, such as US 10DLC carrier surcharges. `null` when this component was not priced; `"0.00000"` when it priced at zero. - `data.tags` (array of object): Structured `{name, value}` filter labels applied to this message. - `data.tags.name` (string, required): Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters. - `data.tags.value` (string, required): 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.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. - `data.options.smart_encoding` (boolean, required): Whether Bird replaced characters outside the GSM-7 alphabet in this message's body with their closest equivalent before sending it. When `true`, `text` is the body as sent and `segments` describes that body. - `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. - `data.last_error.code` (string, required) Standardized failure reason: - `invalid_destination`: The number is unassigned, ported out, or malformed. - `unreachable`: The handset is off or outside coverage. - `blocked_by_carrier`: The carrier filtered the message. - `blocked_by_fraud_protection`: Bird fraud protection blocked suspected SMS pumping. - `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`: The provider remained unavailable after retries. - `insufficient_balance`: The workspace wallet could not fund the send. - `unknown`: The failure could not be classified. This is an open enum. Accept unrecognized values. Possible values (may grow over time): `invalid_destination`, `unreachable`, `blocked_by_carrier`, `blocked_by_fraud_protection`, `blocked_by_recipient`, `landline_unreachable`, `content_rejected`, `sender_unregistered`, `recipient_opted_out`, `provider_unavailable`, `insufficient_balance`, `unknown` - `data.last_error.description` (string, required): The failure in words: the provider's reason text, or Bird's explanation for a fraud protection block or a message refused before submission. Free-form, so branch on `code` and show this to a human. - `data.last_error.carrier_error_code` (nullable string): Raw provider-supplied error code, finer-grained than the `code` that normalizes it. Not a Bird-defined value, so quote it to support when asking why a message failed. Null when the provider sent none, including any failure decided before one was reached. - `data.last_error.occurred_at` (string, required): When the failure occurred. - `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. - `summary.accepted_count` (integer, required): Number of messages accepted in the batch. Acceptance is all-or-nothing, so this equals the number of messages submitted. ## Related resources - [Sending your first SMS](/learn/sms/sending-your-first-sms) (video) - [What does SMS mean?](/explained/sms/what-does-sms-mean) (answer) - [SMS](/sms-api) (product) - [Build your first integration](/learn/paths/integration) (course) [Get an implementation brief](/learn/workspace?topic=sms)