# List SMS suppressions

Retrieve the organization's SMS suppression list (opt-outs and permanent delivery failures).

Source: https://statusdashboard.com/docs/api/subscriptions/sms/suppression/list

`GET /app/subscribers/sms/suppression`

Returns a paginated list of suppressed phone numbers for the organization. Entries are created when a recipient opts out (STOP), when the messaging provider reports a permanent delivery failure, or when a send is rejected because the destination remains on a carrier-level opt-out list.

Requires the `admin` or `subscriber` role and the **SMS notifications** feature entitlement.

***

## Request
See [API Basics](/docs/api) for required headers.

### Query parameters
| Parameter   | Type    | Required | Description                                                                                             |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `limit`     | integer | No       | Max entries per page. Range: 1–100. Default: `10`.                                                      |
| `nextToken` | string  | No       | Next-page bookmark from the previous response — pass unchanged. See [Pagination](/docs/api#pagination). |
| `phone`     | string  | No       | Filter to an exact E.164 phone number (e.g. `+14155552671`). Must be valid E.164 when provided.         |

***

## Sample request
```bash
curl "https://api.statusdashboard.com/app/subscribers/sms/suppression?phone=%2B14155552671" \
  -H "Authorization: Bearer bcf847abf5c6:def456"
```

## Sample response
**Status: `200 OK`**

```json
{
  "suppressions": [
    {
      "phone": "+14155552671",
      "reason": "opt_out",
      "detail": "Inbound STOP keyword",
      "suppressedAt": "2026-06-26T14:30:00.000Z",
      "lastEventAt": "2026-06-26T14:30:00.000Z"
    }
  ],
  "nextToken": null
}
```

***

## Response fields
| Field          | Type           | Description                                                                         |
| -------------- | -------------- | ----------------------------------------------------------------------------------- |
| `suppressions` | array          | Suppression entries for this page.                                                  |
| `nextToken`    | string \| null | Next-page bookmark when more results exist. See [Pagination](/docs/api#pagination). |

### Entry fields
Each `suppressions[]` item:

| Field          | Type              | Description                                                    |
| -------------- | ----------------- | -------------------------------------------------------------- |
| `phone`        | string            | Suppressed number in E.164 format.                             |
| `reason`       | string            | `opt_out`, `invalid`, `carrier_blocked`, `spam`, or `protect`. |
| `detail`       | string \| omitted | Human-readable summary from the event.                         |
| `suppressedAt` | string            | ISO 8601 — first time this number was suppressed.              |
| `lastEventAt`  | string            | ISO 8601 — most recent event for this entry.                   |

***

## Pagination
See [Pagination](/docs/api#pagination) in API Basics. Re-send the same query parameters on every page request.

***

## Retention
Suppression entries **do not expire**. They remain until removed via [DELETE suppression](/docs/api/subscriptions/sms/suppression/delete).

See [SMS suppression list](/docs/notifications/sms#suppression) for how entries are created, what each reason means, and when it is safe to remove a row.

***

## Error responses
| Status | When                                                                                 |
| ------ | ------------------------------------------------------------------------------------ |
| `400`  | Invalid query parameters (e.g. malformed `phone` or `nextToken`).                    |
| `403`  | Missing required role, or the SMS notifications feature is not enabled on your plan. |