<Intro>

<EndpointHeader />

<Description>

Returns a single SMS message: its current delivery status, segment breakdown, cost, and failure detail when it failed. The `status` advances asynchronously as delivery progresses, and `cost` is null until the message has been priced, so poll this endpoint (or subscribe to `sms.*` webhook events) after a send to confirm delivery. To scan messages in bulk, use [List SMS messages](/docs/api/reference/list-sms-messages) instead.

</Description>

</Intro>

<Parameters in="path">

<Parameter name="message_id" type="string">

<Description>

ID of the message (`sms_`-prefixed), as returned in the send response's `id` field.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="id" type="string" required>

<Description>

ID of the message (`sms_`-prefixed), assigned when the send is accepted. Pass it as `message_id` to the get-message endpoint.

</Description>

</Field>

<Field name="direction" type="string" required>

<Description>

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

</Description>

<Description>

Possible values: `outbound`, `inbound`

</Description>

</Field>

<Field name="status" type="object" required />

<Field name="to" type="string" required>

<Description>

Recipient phone number in E.164 format.

</Description>

</Field>

<Field name="from" type="string" required>

<Description>

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

</Description>

</Field>

<Field name="text" type="string" required>

<Description>

The message body as sent. For a template send, this is the rendered text after parameter substitution.

</Description>

</Field>

<Field name="category" type="nullable string">

<Description>

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

</Description>

</Field>

<Field name="segments" type="object" required>

<Description>

Segment breakdown for the body.

</Description>

<FieldChildren kind="response">

<Field name="count" type="integer" prefix="segments." required>

<Description>

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

</Description>

</Field>

<Field name="encoding" type="string" prefix="segments." required>

<Description>

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

</Description>

<Description>

Possible values: `GSM_7BIT`, `UCS2`

</Description>

</Field>

<Field name="characters" type="integer" prefix="segments." required>

<Description>

Character count of the body under the selected encoding.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="cost" type="nullable object">

<Description>

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

</Description>

<FieldChildren kind="response">

<Field name="currency_code" type="string" prefix="cost.">

<Description>

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

</Description>

</Field>

<Field name="amount" type="string" prefix="cost." required>

<Description>

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

</Description>

</Field>

<Field name="breakdown" type="object" prefix="cost.">

<Description>

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

</Description>

<FieldChildren kind="response">

<Field name="per_segment" type="string" prefix="cost.breakdown." required>

<Description>

Per-segment price as a decimal string.

</Description>

</Field>

<Field name="segments" type="integer" prefix="cost.breakdown." required>

<Description>

Number of billable segments.

</Description>

</Field>

<Field name="country_code" type="string" prefix="cost.breakdown." required>

<Description>

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

</Description>

</Field>

<Field name="carrier_surcharge" type="string" prefix="cost.breakdown." required>

<Description>

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

</Description>

</Field>

</FieldChildren>

</Field>

</FieldChildren>

</Field>

<Field name="tags" type="array of object">

<Description>

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

</Description>

<FieldChildren kind="response">

<Field name="name" type="string" prefix="tags." required>

<Description>

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

</Description>

</Field>

<Field name="value" type="string" prefix="tags." required>

<Description>

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

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="metadata" type="object">

<Description>

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

</Description>

</Field>

<Field name="validity_period" type="integer">

<Description>

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

</Description>

</Field>

<Field name="carrier" type="nullable string">

<Description>

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

</Description>

</Field>

<Field name="mcc_mnc" type="nullable string">

<Description>

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

</Description>

</Field>

<Field name="last_error" type="nullable object">

<Description>

Failure detail on a terminally failed or rejected message. Present only when the message failed.

</Description>

<FieldChildren kind="response">

<Field name="code" type="string" prefix="last_error." required>

<Description>

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. `insufficient_balance`: the workspace wallet had insufficient balance to send the message. `unknown`: an unmapped failure.

</Description>

<Description>

Possible values: `invalid_destination`, `unreachable`, `blocked_by_carrier`, `blocked_by_recipient`, `landline_unreachable`, `content_rejected`, `sender_unregistered`, `recipient_opted_out`, `provider_unavailable`, `insufficient_balance`, `unknown`

</Description>

</Field>

<Field name="description" type="string" prefix="last_error." required>

<Description>

Human-readable explanation of the failure.

</Description>

</Field>

<Field name="carrier_error_code" type="nullable string" prefix="last_error.">

<Description>

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

</Description>

</Field>

<Field name="occurred_at" type="string" prefix="last_error." required>

<Description>

When the failure occurred.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="created_at" type="string" required>

<Description>

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

</Description>

</Field>

<Field name="sent_at" type="nullable string">

<Description>

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

</Description>

</Field>

<Field name="delivered_at" type="nullable string">

<Description>

When delivery was confirmed. Null until then.

</Description>

</Field>

</Payload>