---
title: "List SMS suppressions"
method: GET
path: "/v1/sms/suppressions"
tags: ["sms-suppressions"]
---

# List SMS suppressions

`GET /v1/sms/suppressions`

## Request

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

Returns the suppressions currently stopping your messages, most recent opt-out first. Pass `destination` to look up one subscriber before sending to them.

A suppression covers one sender and one subscriber, so the same number can appear more than once: opting out of one of your senders does not opt out of the others.

Ended suppressions are excluded. A subscriber who opted back in is reachable again and does not appear in this list.

## Query parameters

- `destination` string
- `originator` string
- `reason` 'keyword_stop' | 'carrier_opted_out' | 'manual'
- `limit` integer
- `starting_after` string
- `ending_before` string

## Headers

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

## Response `200`

Paginated list of SMS suppressions.

- SMSSuppressionList
  - `data` SMSSuppression[], required: Page of suppressions, most recent opt-out first.
    - `id` string, required
    - `destination` string, required: The subscriber, in E.164 format.
    - `originator` string, required: The sender this stops. A suppression covers one sender, so your other senders still reach this subscriber. Opting out of one of your programs does not opt out of the others.
    - `reason` string, required: Reason this sender cannot message the subscriber: - `keyword_stop`: The subscriber sent a stop keyword. A start keyword clears it. - `carrier_opted_out`: The carrier reported the opt-out. - `manual`: Your workspace added the suppression through the API or dashboard. This is an open enum. Accept unrecognized values.
    - `origin` string, required: How the opt-out reached us: - `keyword`: an inbound message from the subscriber. - `dlr_event`: a carrier delivery report. - `api_key`: an API call. - `user`: someone acting in the dashboard. Kept beside the reason because one reason can arrive by more than one route. This list grows over time, so treat an unknown value as informational rather than rejecting the record.
    - `applies_to` string, required: Message categories blocked for this sender and subscriber. `all` blocks every category, including authentication and transactional messages. `non_transactional` blocks marketing messages only. Responses currently use `all`. Treat unrecognized values as blocking every category.
    - `blocking` boolean, required: Whether this is stopping messages right now. Always true in a list, which carries only the suppressions in force; false when you fetch one by ID that has since ended, which is also when `ended_at` is set.
    - `source_sms_id` string
    - `effective_at` string, date-time, required: When the subscriber opted out, as reported by whoever reported it. This is what orders one subscriber's history, and it can be earlier than `created_at` when a message reached us late.
    - `ended_at` string, date-time, nullable: When this stopped applying. Null while it is still stopping messages.
    - `ended_reason` string: What ended it: - `keyword_start`: the subscriber texting a start keyword to the same sender. - `api_key`: an API call. - `user`: someone acting in the dashboard. - `carrier_cleared`: the carrier reporting its own opt-out cleared. This list grows over time, so treat an unknown value as informational rather than rejecting the record.
    - `ended_effective_at` string, date-time, nullable: When the subscriber opted back in, as reported. Null while it is still stopping messages.
    - `source_end_sms_id` string
    - `created_at` string, date-time, required: When we recorded it.
    - `last_asserted_at` string, date-time, required: When we last recorded the subscriber opting out of this sender. Later than `created_at` when they texted a stop keyword again while already suppressed, which adds no new record but does earn another confirmation reply.
  - `next_cursor` string, nullable, required: Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
  - `prev_cursor` string, nullable, required: Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
  - `refresh_cursor` string, nullable, required: 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`.

## 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

---

[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/6dfce1179799?raw)