---
title: "List events for an SMS message"
method: GET
path: "/v1/sms/messages/{message_id}/events"
tags: ["sms-messages"]
---

# List events for an SMS message

`GET /v1/sms/messages/{message_id}/events`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/sms/messages/{message_id}/events`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Returns the lifecycle event timeline for a message, in chronological order.

## Path parameters

- `message_id` string, required

## Query parameters

- `type` string

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

Event timeline for this message.

- SMSEventList
  - `data` SMSEvent[], required: Timeline events for this SMS message, in chronological order. The bounded timeline is returned in full and is not paginated.
    - `id` string, required: Unique identifier for this event, stable across repeated fetches of the message.
    - `type` string, required: Lifecycle event type. The `sms.accepted` event means the API accepted the request. The `sms.sent` event means the message reached the carrier. The `sms.delivered` event confirms delivery. The `sms.undelivered`, `sms.failed`, and `sms.expired` events describe delivery failures. The `sms.rejected` event means the message was refused before carrier handoff. This is an open enum. Accept unrecognized values.
    - `occurred_at` string, date-time, required: When this event occurred.
    - `carrier` string: Carrier that handled the message. Present on `sms.sent` and `sms.delivered` once identified, absent otherwise.
    - `mcc_mnc` string: Mobile country code and mobile network code of the carrier. Present on `sms.sent` and `sms.delivered` once identified, absent otherwise.
    - `error` SMSError, nullable: Failure detail for a message that could not be delivered or was rejected.
      - `code` string, required: 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.
      - `description` string, required: 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.
      - `carrier_error_code` string, nullable: 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.
      - `occurred_at` string, date-time, required: When the failure occurred.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)