---
title: "List allowlist or look up an address"
method: GET
path: "/v1/suppression"
tags: ["Suppression"]
---

# List allowlist or look up an address

`GET /v1/suppression`

## Request

- Base URL: `https://api.mails.ai`
- URL: `https://api.mails.ai/v1/suppression`
- Auth: HTTP bearer

**Requires scope:** `read`. Three answers from one route. With `?address=`, the suppression status of that address. With `?view=suppressed`, which of your own recent recipients are suppressed for you, and why (up to 500, in one page; addresses are stored hashed, so the list itself cannot be browsed). Without either, the workspace allowlist (paginated).

## Query parameters

- `address` string, email
- `view` 'suppressed'
- `limit` integer
- `cursor` string

## Response `200`

A suppression lookup (when `address` is set), your suppressed recipients (when `view=suppressed`), or a page of allowlist entries.

- union
  - SuppressionLookup
    - `suppressed` boolean, required: True when your sends to the address are refused: it hard-bounced or drew a spam complaint for any mails.ai sender, or unsubscribed from your mail. An allowlist entry lifts all but a hard bounce, and then this is false with `allowed` set.
    - `type` 'hard_bounce' | 'complaint' | 'unsubscribe': Present only when suppressed.
    - `scope` string: `global` (hard bounces and complaints, for every sender) or `workspace:<your id>` (an unsubscribe from your mail). Present only when suppressed.
    - `since` string, date-time: When suppression began. Present only when suppressed.
    - `allowed` object: Present when an allowlist attestation overrides the suppression.
      - `id` string, required: Id of the allowlist entry (`sup_…`) that lifts the suppression.
      - `attestation` string: The consent statement given when the entry was added.
      - `created_at` string: When the entry was added (ISO 8601, UTC).
  - object
    - `data` SuppressedRecipient[], required: Your suppressed recipients, newest suppression first, at most 500 rows. Every `to`, `cc` and `bcc` address of your 2,000 most recent sends is checked (for a key tied to one agent, that agent's).
      - `address` string, email, required: One of this workspace's recent recipients.
      - `type` 'hard_bounce' | 'complaint' | 'unsubscribe', required: Why the address is suppressed. An address suppressed for more than one reason has a row for each; a reason an allowlist entry lifts is left out.
      - `scope` string, required: `global`, or `workspace:<your id>` for an unsubscribe from your mail.
      - `detail` string: What caused it, when recorded.
      - `suppressed_at` string, date-time, required: When the suppression was recorded (UTC).
    - `has_more` boolean, required: `true` when more of those recipients are suppressed than the 500 returned. This view takes no `limit` or `cursor`, so check any other address with `?address=`.
    - `next_cursor` string: Pass as `cursor` to fetch the next page. Absent on the last page.
  - object
    - `data` SuppressionEntry[], required: The items on this page, at most `limit` of them.
      - `id` string, required: Allowlist entry id (`sup_…`); revoke it with `DELETE /v1/suppression/allow/{id}`.
      - `address` string, email, required: The address the entry covers. The create response echoes it as sent; the list shows it as matched: lowercase, without a `+tag`, and for Gmail without dots before the `@`.
      - `attestation` string, required: Your statement that the recipient agreed to receive your mail, as given when the entry was added.
      - `revoked_at` string, date-time: When the entry was revoked. Absent while it is active; a revoked entry stays in the list but lifts nothing.
      - `created_at` string, date-time, required: When the entry was added (UTC).
    - `has_more` boolean, required: True when more items follow this page: pass `next_cursor` as `cursor` to get them.
    - `next_cursor` string: Pass as `cursor` to fetch the next page. Absent on the last page.

## Other responses

- `400`: Invalid request — malformed JSON or a field failed validation. Also `feature_not_enabled` when this server has a feature switched off (custom domains before they are available).
- `401`: Missing or invalid API key.
- `403`: The API key lacks the required scope (`insufficient_scope`), or the token belongs to an app connected by sign-in and this operation is closed to connected apps (`connected_app_not_allowed`).
- `500`: Internal server error.

---

[API](https://skmtc.dev/mails/apis/mails-ai-api.md) · [All operations](https://skmtc.dev/mails/apis/mails-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mails/apis/mails-ai-api/revisions/4d4930a8c33b?raw)