# Get an Apple Messages for Business suppression

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

Returns the suppression episode for the given ID, including one that has already ended. An ended episode keeps its dates and reports when and how it ended.

## Code samples

**TypeScript**

```ts
const result = await bird.amb.suppressions.get(
  "asp_01krdgeqcxet5s7t44vh8rt9mg",
);
console.log(result);
```

Examples: [TypeScript](/docs/api/reference/get-amb-suppression.ts.md) · [Python](/docs/api/reference/get-amb-suppression.py.md) · [Go](/docs/api/reference/get-amb-suppression.go.md) · [PHP](/docs/api/reference/get-amb-suppression.php.md) · [CLI](/docs/api/reference/get-amb-suppression.cli.md) · [MCP](/docs/api/reference/get-amb-suppression.mcp.md) · [cURL](/docs/api/reference/get-amb-suppression.curl.md)

## Example response `200`

```json
{
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z",
  "id": "asp_01krdgeqcxet5s7t44vh8rt9mg",
  "business_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
  "handle": "+15551234567",
  "handle_type": "opaque_user_id",
  "reason": "manual",
  "origin": "user",
  "applies_to": "all",
  "source_message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
  "source_end_message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
  "effective_at": "2026-08-12T09:00:00Z",
  "ended_at": null,
  "ended_reason": null,
  "ended_effective_at": null
}
```

## Path parameters

- `suppression_id` (string)

## Response body

- `created_at` (string, required)
- `updated_at` (string, required)
- `id` (string, required): Unique identifier for the suppression episode.
- `business_id` (nullable string): The brand this episode applies to, or null when it covers every brand in the workspace. Apple requires that a brand not message someone who opted out of it, so an episode scoped to one brand does not suppress a sibling brand in the same workspace.
- `handle` (string, required): The suppressed phone number or opaque identifier. `handle_type` says which. For a phone number this is canonical E.164 with a leading plus sign.
- `handle_type` (string, required)

  What kind of value `handle` holds.

  - `phone_number` means `handle` is the customer's phone number. Apple's CloseSession event carries a phone number rather than an opaque identifier, so a suppression opened by a close on a conversation identified by phone number takes this kind.
  - `opaque_user_id` means `handle` is the opaque identifier Apple assigns to the customer's conversation with the business, stable across a close and a later re-initiation.

  Possible values: `phone_number`, `opaque_user_id`
- `reason` (string, required)

  Why the handle is suppressed. `manual` means it was added directly through this API or the dashboard. `opted_out` covers every case where Apple or the customer signaled they should not be contacted: a close, a permanent delivery failure, a declined invitation, or a stop keyword. This list grows over time, so treat an unknown value as informational rather than rejecting the record.

  Possible values (may grow over time): `manual`, `opted_out`
- `origin` (string, required)

  How this episode came to exist.

  - `user` means a dashboard user added it directly.
  - `api_key` means an API caller added it directly.
  - `close_session` means the customer sent Apple's close event, ending the conversation.
  - `gone` means a send to the handle returned Apple's permanent-failure response, which Bird treats as the same signal as a close.
  - `invitation_declined` means the customer declined an invitation. No operation writes this value yet; it starts once invitations ship.
  - `keyword` means the customer sent a stop keyword. No operation writes this value yet; it starts once keyword automation ships.

  Possible values: `user`, `api_key`, `close_session`, `gone`, `invitation_declined`, `keyword`
- `applies_to` (string, required)

  What this episode blocks. `all` blocks every outbound path: operator and automated replies, API sends, typing indicators, and invitations. `invitations` blocks only a new invitation to the handle, leaving replies in a conversation the customer opens directly unaffected; no operation writes this value yet, since invitations are a future feature. This list grows over time, so treat an unknown value as blocking.

  Possible values (may grow over time): `all`, `invitations`
- `source_message_id` (nullable string): ID of what opened this episode. A permanent delivery failure on send names the message that failed, an `amb_` id. A close names the conversation event Bird recorded for it instead, an `aev_` id, because a close carries no message of its own. Null for an episode opened directly through this API or by a phone-addressed close that has no conversation event.
- `source_end_message_id` (nullable string): ID of the inbound message that ended this episode by re-initiating the conversation. Null while the episode is still in force, and null for an episode ended through this API instead.
- `effective_at` (string, required): When this episode started blocking outbound messages.
- `ended_at` (nullable string): When this episode stopped applying. Null while it is still blocking outbound messages, which is the case for every episode the list returns.
- `ended_reason` (nullable string)

  What ended it. `reinitiated` means the same customer started the conversation again: this ends an episode opened by `close_session` or `gone` automatically, with no API call, and does not apply to one opened by `invitation_declined`, which needs an explicit re-subscription instead. `user` and `api_key` mean this API ended it directly, which works for an episode of any origin. Null while the episode is still in force.

  Possible values (may grow over time): `user`, `api_key`, `reinitiated`
- `ended_effective_at` (nullable string): When the ended state took effect, which can differ from `ended_at` when the record of an end arrives later than the event that caused it.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)