<Intro>

<EndpointHeader />

<Description>

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.

Suppressions that have ended are not listed. A subscriber who opted out and then opted back in is reachable again, so they are not on this list, and what you have here is the answer to "who can I not message right now".

</Description>

</Intro>

<Parameters in="query">

<Parameter name="destination" type="string">

<Description>

Return only suppressions for this subscriber, in E.164 format. Exact match, not a prefix: a phone number is not a string a partial match is meaningful on.

</Description>

</Parameter>

<Parameter name="originator" type="string">

<Description>

Return only suppressions covering this sender.

</Description>

</Parameter>

<Parameter name="reason" type="string">

<Description>

Return only suppressions with this reason:

- `keyword_stop`: The subscriber texted a stop keyword to the sender.
- `carrier_opted_out`: Their carrier reported the opt-out.
- `manual`: Added through this API or the dashboard.

</Description>

<Description>

Possible values: `keyword_stop`, `carrier_opted_out`, `manual`

</Description>

</Parameter>

<Parameter name="limit" type="integer">

<Description>

Maximum number of items to return per page.

</Description>

</Parameter>

<Parameter name="starting_after" type="string">

<Description>

Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.

</Description>

</Parameter>

<Parameter name="ending_before" type="string">

<Description>

Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="data" type="array of object" required>

<Description>

Page of suppressions, most recent opt-out first.

</Description>

<FieldChildren kind="response">

<Field name="id" type="string" prefix="data." required />

<Field name="destination" type="string" prefix="data." required>

<Description>

The subscriber, in E.164 format.

</Description>

</Field>

<Field name="originator" type="string" prefix="data." required>

<Description>

The sender this stops. A suppression covers one sender, so your other senders still reach this subscriber. Opting out of one of your programmes is not opting out of all of them.

</Description>

</Field>

<Field name="reason" type="string" prefix="data." required />

<Field name="origin" type="string" prefix="data." required />

<Field name="applies_to" type="string" prefix="data." required />

<Field name="blocking" type="boolean" prefix="data." required>

<Description>

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.

</Description>

</Field>

<Field name="source_sms_id" type="nullable string" prefix="data.">

<Description>

The inbound message the subscriber opted out with, or the outbound message whose delivery report reported the opt-out. Null when neither applies.

</Description>

</Field>

<Field name="effective_at" type="string" prefix="data." required>

<Description>

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.

</Description>

</Field>

<Field name="ended_at" type="nullable string" prefix="data.">

<Description>

When this stopped applying. Null while it is still stopping messages.

</Description>

</Field>

<Field name="ended_reason" type="nullable string" prefix="data.">

<Description>

What ended it. Null while it is still stopping messages.

</Description>

</Field>

<Field name="ended_effective_at" type="nullable string" prefix="data.">

<Description>

When the subscriber opted back in, as reported. Null while it is still stopping messages.

</Description>

</Field>

<Field name="source_end_sms_id" type="nullable string" prefix="data.">

<Description>

The inbound message the subscriber opted back in with, when there was one. Null while it is still stopping messages, and when something other than a start keyword ended it.

</Description>

</Field>

<Field name="created_at" type="string" prefix="data." required>

<Description>

When we recorded it.

</Description>

</Field>

<Field name="last_asserted_at" type="string" prefix="data." required>

<Description>

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.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="next_cursor" type="nullable string" required>

<Description>

Cursor for the next page. Pass back as `starting_after` to advance forward. Null when no next page exists.

</Description>

</Field>

<Field name="prev_cursor" type="nullable string" required>

<Description>

Cursor for the previous page. Pass back as `ending_before` to step backward. Null when no previous page exists.

</Description>

</Field>

<Field name="refresh_cursor" type="nullable string" required>

<Description>

Refresh anchor. Pass back as `ending_before` later to fetch items that have appeared since this response. Non-null whenever `data` is non-empty; null only on an empty page. Distinct from `prev_cursor`.

</Description>

</Field>

</Payload>