List SMS messages
GET
/v1/sms/messages
curl -X GET "https://us1.platform.bird.com/v1/sms/messages" \
-H "Authorization: Bearer $TOKEN" \
--url-query "limit=25"Returns a paginated list of SMS messages in the workspace, newest first.
Paramètres de requête
limit
integer
Maximum number of items to return per page.
starting_after
string
Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.
ending_before
string
Cursor from the prev_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order.
created_after
string
Return only resources created strictly after this timestamp. RFC 3339 / ISO 8601 with timezone.
created_before
string
Return only resources created strictly before this timestamp. RFC 3339 / ISO 8601 with timezone.
direction
string
Filter by direction. Omit for both.
status
array
Filter by status; repeat the parameter to match any of several. One of scheduled, accepted, sent, delivered, undelivered, failed, rejected, canceled, expired, or received.
error_code
array
Filter to messages whose failure reason matches one of the supplied values; repeat the parameter to match any of several. One of invalid_destination, unreachable, blocked_by_carrier, blocked_by_recipient, landline_unreachable, content_rejected, sender_unregistered, recipient_opted_out, provider_unavailable, or unknown.
category
string
Filter by category.
to
string
Filter by recipient phone number (E.164 exact match).
from
string
Filter by sender (E.164, alphanumeric, or short code — exact match).
tag
array
Filter by tag. Accepts name to match any message carrying that tag name, or name:value to match a specific tag pair. Repeat the parameter to AND-combine several tag filters.
Contenu de la réponse
data
array of object
obligatoire
Page of message objects.
Afficher les attributs enfants
data.id
string
obligatoire
Message ID.
data.direction
string
obligatoire
Whether the message was sent from a Bird sender (outbound) or received from a subscriber (inbound).
data.status
object
obligatoire
data.to
string
obligatoire
Recipient phone number in E.164 format.
data.from
string
obligatoire
Sender the message was sent from — an E.164 number, an alphanumeric sender ID, or a short code.
data.text
string
obligatoire
Message body.
data.category
nullable string
Content classification supplied on the send. Null for inbound messages.
data.segments
object
obligatoire
Segment breakdown for the body.
Afficher les attributs enfants
data.segments.count
integer
obligatoire
Number of segments the body is split into. Each segment is a billable unit.
data.segments.encoding
string
obligatoire
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
obligatoire
Character count of the body under the selected encoding.
data.cost
nullable object
Cost of the message. Null until the message has been priced.
Afficher les attributs enfants
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
obligatoire
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.
Afficher les attributs enfants
data.cost.breakdown.per_segment
string
obligatoire
Per-segment price as a decimal string.
data.cost.breakdown.segments
integer
obligatoire
Number of billable segments.
data.cost.breakdown.country_code
string
obligatoire
ISO 3166-1 alpha-2 destination country the price was resolved for.
data.cost.breakdown.carrier_surcharge
string
obligatoire
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.
Afficher les attributs enfants
data.tags.name
string
obligatoire
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
data.tags.value
string
obligatoire
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.
Afficher les attributs enfants
data.last_error.code
string
obligatoire
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
obligatoire
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
obligatoire
When the failure occurred.
data.created_at
string
obligatoire
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.
next_cursor
nullable string
obligatoire
Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.
prev_cursor
nullable string
obligatoire
Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.
refresh_cursor
nullable string
obligatoire
Refresh anchor. Pass back as ending_before later to fetch items that have appeared since this response. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.