---
title: "Get an SMS suppression"
method: GET
path: "/v1/sms/suppressions/{suppression_id}"
tags: ["sms-suppressions"]
---

# Get an SMS suppression

`GET /v1/sms/suppressions/{suppression_id}`

## Request

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

Returns one suppression: the sender and subscriber it covers, why messages are stopped, how the record came to exist, what it blocks, and whether it is still in force.

This operation also returns a suppression that has already ended. The `blocking` field is `false`, and the `ended_*` fields say when and why. An ID you kept from a create or delete therefore stays readable. To find one when you only know the number, use `GET /v1/sms/suppressions` with the `destination` parameter. An ID that does not exist in the workspace returns `404`.

## Headers

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

## Response `200`

SMS suppression.

- SMSSuppression: One period during which a sender's messages to a subscriber are stopped: when it started, what started it, and what ended it. A subscriber who opts out, opts back in, and opts out again has three of these on record rather than one current state, and each keeps its own dates once it ends. The list returns the periods in force; fetch one by ID to read an ended one.
  - `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.

## 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/3e2a50466454?raw)