Get an SMS message
/v1/sms/messages/{message_id}const msg = await bird.sms.get("sms_abc123");
msg.status; // "accepted" | "delivered" | …message = client.sms.get("sms_abc123")
print(message.id, message.status)$message = $bird->sms->get('sms_01krdgeqcxet5s7t44vh8rt9mg');
echo $message->getStatus();bird sms get <message-id>curl -X GET "https://us1.platform.bird.com/v1/sms/messages/{message_id}" \
-H "Authorization: Bearer $TOKEN"{
"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"
}
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 operation (or subscribe to sms.* webhook events) after a send to confirm delivery. To scan messages in bulk, use List SMS messages instead.
Parameters
message_idstringID of the message, as returned in the send response's id field.
Response Payload
idID of the message, assigned when the send is accepted. Pass it as message_id to the get-message endpoint.
directionWhether the message was sent from a Bird sender (outbound) or received from a subscriber (inbound).
Possible values: outbound, inbound
statusDelivery 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
toWhere 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.
fromWhere 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.
textThe 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.
binaryThe payload of a binary send, in place of text. Absent on every other message.
categoryContent classification supplied for free text or derived from the template. Null for inbound messages.
requested_languageThe template language requested by the send, in canonical form. Null when the send named no language or used no template.
resolved_languageThe 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_idThe template rendered for this message, or null for a free-text message.
template_version_idThe 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_hashThe rendered language's source fingerprint, or null for a free-text message.
messaging_profile_idThe messaging profile this message was sent or received under. Absent when no messaging profile applied.
costWhat the message cost, split into Bird's charge and any third-party fees passed through. Null until the message has been priced.
tagsStructured {name, value} filter labels applied to this message.
metadataArbitrary JSON metadata stored on the message and echoed in webhook payloads.
optionsThe 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.
validity_periodThe validity_period applied to the message, in seconds: the send's own, or else its messaging profile's. Absent when neither set one.
referenceThe reference from the send request. Absent when the send set none, and on inbound messages.
cost_centerThe 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.
carrierCarrier 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_mncMobile country code and mobile network code of the carrier. Absent until the carrier is identified.
last_errorFailure detail on a message that failed, was rejected, was not delivered, or expired. Absent otherwise.
country_codeOn 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_messageOn 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.
created_atWhen the message was accepted (outbound) or received (inbound).
sent_atWhen the message was handed to the carrier. Null until then.
delivered_atWhen delivery was confirmed. Null until then.
Related resources
Continue with the documentation, guides and examples for this topic.