List SMS messages

GET

/v1/sms/messages

for await (const msg of bird.sms.list({ direction: "outbound" })) {
  console.log(msg.id, msg.status);
}

for message in client.sms.list(direction="outbound"):
    print(message.id, message.status)

foreach ($bird->sms->list(['direction' => 'outbound']) as $message) {
    echo $message->getId(), ' ', $message->getStatus(), "\n";
}

bird sms list

curl -X GET "https://us1.platform.bird.com/v1/sms/messages" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "limit=25"

Réponse200

{
  "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"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Returns the workspace's SMS messages as a cursor-paginated list, newest first. Filter by direction, status, category, recipient, sender, failure reason, tag, or creation time; pass the response's next_cursor back as starting_after to fetch the next page. To follow a single message's delivery, use Get an SMS message instead.

Messages are retained for 30 days. A created_after earlier than that is accepted and raised to the retention bound rather than rejected, so a wider window returns what is still retained instead of failing. Messages older than the retention window cannot be retrieved.

Paramètres de requête

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

created_afterstring

Limits the response to resources created at or after this timestamp. Combine it with created_before to select a time window. Use an RFC 3339 timestamp with a timezone offset.

created_beforestring

Limits the response to resources created before this timestamp. Combine it with created_after to select a time window. Use an RFC 3339 timestamp with a timezone offset.

directionstring

Filter by direction. Omit for both.

Possible values: outbound, inbound

statusarray

Keep only messages whose current status matches; repeat the parameter to match any of several. One of scheduled, accepted, sent, delivered, undelivered, failed, rejected, canceled, expired, or received. scheduled and canceled are accepted but match nothing until send-later scheduling ships.

error_codearray

Keep only messages whose failure reason (last_error.code) matches; repeat the parameter to match any of several. One of 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, or unknown.

categorystring

Filter by category.

Possible values: transactional, marketing, authentication, service

tostring

Filter by recipient phone number (E.164 exact match).

fromstring

Filter by sender (E.164, alphanumeric, or short code; exact match).

tagarray

Filter by tag. Accepts name to match any record carrying that tag name, or name:value to match a specific tag pair (for example category:welcome). Repeat the parameter to add more tags. A record must match every tag listed to be returned.

Contenu de la réponse

data

array of object

obligatoire

Page of SMS messages, newest first.

Afficher les attributs enfants

data.id

string

obligatoire

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

data.direction

string

obligatoire

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

Possible values: outbound, inbound

data.status

string

obligatoire

data.to

string

obligatoire

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

obligatoire

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

obligatoire

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

obligatoire

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

obligatoire

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

data.template_version_id

nullable string

obligatoire

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

obligatoire

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

data.segments

object

obligatoire

Segment breakdown for the body.

Afficher les attributs enfants

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.

Afficher les attributs enfants

data.tags

array of object

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

Afficher les attributs enfants

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.

Afficher les attributs enfants

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.

Afficher les attributs enfants

data.last_error.code

string

obligatoire

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

obligatoire

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

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, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Essayez la pratique et obtenez un guide d'implémentation

for await (const msg of bird.sms.list({ direction: "outbound" })) {
  console.log(msg.id, msg.status);
}

for message in client.sms.list(direction="outbound"):
    print(message.id, message.status)

foreach ($bird->sms->list(['direction' => 'outbound']) as $message) {
    echo $message->getId(), ' ', $message->getStatus(), "\n";
}

bird sms list

curl -X GET "https://us1.platform.bird.com/v1/sms/messages" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "limit=25"

Réponse200

{
  "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"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

List SMS messages

Paramètres de requête

Contenu de la réponse

Ressources associées