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

Create an SMS message

POST
/v1/sms/messages
const msg = await bird.sms.send({
  from: "+15557654321",
  to: "+14155550100",
  text: "Your verification code is 123456.",
  category: "authentication",
});
console.log(msg.id, msg.status);
Response202
{
  "id": "sms_01krdgeqcxet5s7t44vh8rt9mg",
  "direction": "outbound",
  "status": "scheduled",
  "to": "+15551234567",
  "from": "+15557654321",
  "text": "Your order has shipped and is on its way.",
  "binary": {
    "udh": "0605041582158A",
    "data": "C0FFEE"
  },
  "category": "transactional",
  "requested_language": "pt-BR",
  "resolved_language": "pt-BR",
  "template_id": "smt_01krdgeqcxet5s7t44vh8rt9mg",
  "template_version_id": "smv_01krdgeqcxet5s7t44vh8rt9mg",
  "template_content_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "messaging_profile_id": "mpr_01krdgeqcxet5s7t44vh8rt9mg",
  "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
  },
  "reference": "INV-1234",
  "cost_center": "CC001234",
  "carrier": "Verizon",
  "mcc_mnc": "311480",
  "last_error": {
    "code": "invalid_destination",
    "description": "Carrier filtered as spam"
  },
  "country_code": "US",
  "in_reply_to_message": {
    "id": "sms_01krdgeqcxet5s7t44vh8rt9mg",
    "text": "Reply YES to confirm your appointment on Friday.",
    "sent_at": "2026-10-22T10:14:04.001Z"
  },
  "created_at": "2026-05-21T12:00:00Z"
}

Sends one SMS to one recipient with exactly one content form: text, which requires category and from, or a stored template, which supplies its category. A workspace template requires from, while a built-in template selects its sender. To submit up to 100 independent messages in one request, use Send a batch of SMS messages instead.

The 202 Accepted response means the API durably accepted the message for asynchronous delivery. Delivery remains pending; follow it with Get an SMS message or by subscribing to sms.* webhook events.

An invalid field, more than 12 segments, a disabled destination country, or a sender not permitted for the destination returns 422. Insufficient wallet balance returns 402.

Request Payload

to
string
required

Recipient phone number in E.164 format (for example +14155550100), or in national format when you also pass to_country_code. One recipient per message. The number is stored and returned in canonical E.164; a recipient that cannot be routed returns a 422 SMSInvalidRecipient.

to_country_code
string

The ISO 3166-1 alpha-2 country whose national numbering plan to is written in, such as NL for 0612345678. Bird converts to to E.164 before checking the destination, price and sender. An E.164 to is still accepted when its country calling code matches this country; a mismatch, or a national number that is not valid in this country, returns a 422 SMSInvalidRecipient. Omit it to send to in E.164.

from
string

Sender the workspace holds: a number it owns in E.164, such as +15557654321, a short code, such as 24680, or an alphanumeric sender ID it has claimed, such as MyBrand. Any other sender returns 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 a workspace-template send, unless the profile in messaging_profile_id selects a sender for the destination country or has a default sender; omitting it otherwise returns 422. A built-in template selects its sender itself and rejects from.

text
string
required

Free-text message body, required unless template is set; the two are mutually exclusive. From 1 character up to 12 segments, roughly 1836 GSM-7 or 804 UCS-2 characters, since the two encodings fit different numbers of characters in a segment. Bird does not truncate: a longer body returns 422.

category
string

Content classification: why you are sending. Required on a free-text send unless the messaging profile in messaging_profile_id sets a default category; 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.

Possible values: transactional, marketing, authentication, service

validity_period
integer

How long, in seconds (60-172800), the message may wait for delivery after acceptance. Bird does not submit it to the carrier after that deadline, and passes the remaining time to the carrier where the route supports it. A message that misses the deadline before reaching the carrier ends rejected or failed; expired comes only from a carrier report. Omit it to use the validity period of the profile in messaging_profile_id, or the carrier's own rules when the profile sets none.

reference
string

An identifier you want to find this message by, such as an order or ticket number, matched exactly by the message list's reference filter. Set it only when you need to search on it, and put any other data in metadata. Stored on the message, returned on reads and echoed in webhook payloads. Several messages can share one.

cost_center
string

Your accounting identifier for this message, such as a department code. Stored on the message and its usage record, returned on reads, and echoed in webhook payloads. Omit it to use the cost center of the messaging profile in messaging_profile_id. Accepting it does not change how the message is priced.

tags
array of object

Structured {name, value} labels, up to 20 per send. You can filter the list endpoint by tag name, slice analytics by tag, and read them in webhook payloads. Use them for low-cardinality dimensions such as category or experiment_variant, and metadata for context you do not filter by.

Show child parameters
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.

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.

Show child parameters
media_urls
array of string

Preview feature: multimedia (MMS) attachments. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.

messaging_profile_id
string

The messaging profile that supplies this message's sender and defaults. Without from, Bird sends from the profile's sender for the destination country, or its default sender. An omitted category on a free-text send, smart_encoding, cost_center, validity_period, options.callback_url and options.ignore_suppression take the profile's settings, and values set on the message take precedence. A built-in template sends from Bird's system sender and ignores the profile's senders. A profile that does not exist in this workspace returns 422 SMSMessagingProfileNotFound, and a from bound to a different profile returns 422 SMSMessagingProfileSenderBound.

scheduled_at
string

Preview feature: send-later scheduling. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.

broadcast_id
string

Preview feature: broadcast correlation. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.

campaign_id
string

Preview feature: campaign correlation for analytics. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.

audience_id
string

Preview feature: audience-targeted sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.

contact_id
string

Preview feature: contact-targeted sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.

topic_id
string

Preview feature: topic-gated sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.

personalization
object

Preview feature: per-recipient substitution for batch sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.

Response Payload

id
string
required

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

direction
string
required

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

Possible values: outbound, inbound

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

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.

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.

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, and on a binary message, which returns binary instead. For a template send, this is the rendered text after parameter substitution. System template messages preserve the surrounding text and mask sensitive codes with one asterisk per digit. Authentication messages without declared sensitive variables return **REDACTED**. The recipient receives the real code; message history retains only its masked representation.

binary
object

The payload of a binary send, in place of text. Absent on every other message.

Show child attributes
category
nullable string

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

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.

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.

template_id
nullable string
required

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

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.

template_content_hash
nullable string
required

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

messaging_profile_id
string

The messaging profile this message was sent or received under. Absent when no messaging profile applied.

segments
object
required

Segment breakdown for the body.

Show child attributes
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
tags
array of object

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

Show child attributes
metadata
object

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

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 received messages, and on any outbound message for which no settings were recorded.

Show child attributes
validity_period
integer

The validity_period applied to the message, in seconds: the send's own, or else its messaging profile's. Absent when neither set one.

reference
string

The reference from the send request. Absent when the send set none, and on inbound messages.

cost_center
string

The cost_center applied to the message: the send's own, or else its messaging profile's. Absent when neither set one, and on inbound messages.

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.

mcc_mnc
string

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

last_error
nullable object

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

Show child attributes
country_code
string

On an outbound message, the country of the recipient's number. On a received message, the country of the sender's number, or of your number that received it when the sender is not a phone number, such as a short code or an alphanumeric sender. The same value as the message's sms.* events' country_code. Absent when not known.

in_reply_to_message
object

On a received message, the outbound message it was paired with through its messaging profile's outbound matching. Absent on outbound messages and on received messages that were not paired.

Show child attributes
in_reply_to_message.id
string
required

ID of the outbound message.

in_reply_to_message.text
string

Text of the outbound message as Bird stored it, with sensitive template values masked. Authentication messages without declared sensitive variables read **REDACTED**. Absent once that message is past the read window.

in_reply_to_message.sent_at
string

Time Bird handed the outbound message to the carrier; the matching window counts from here. Absent once that message is past the read window.

created_at
string
required

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

sent_at
nullable string

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

delivered_at
nullable string

When delivery was confirmed. Null until then.

Related resources

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

Try the practice and get an implementation brief