import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.suppression.list({
  limit: 10,
});
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.list_suppression(limit=10)
print(result)

curl 'https://api.mails.ai/v1/suppression?limit=10' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails suppressions list
mails suppressions list --address jordan@example.com

{
  "name": "mails_suppressions_list",
  "arguments": { "limit": 10 }
}

{
  "suppressed": false,
  "type": "hard_bounce",
  "scope": "<scope>",
  "since": "2026-10-04T12:00:00.000Z",
  "allowed": {
    "id": "sup_01JZX8K3M9Q4P7VN2YB6RTDC0E",
    "attestation": "<attestation>",
    "created_at": "<created_at>"
  }
}

200  A suppression lookup (when address is set), your
     suppressed recipients (when view=suppressed), or a
     page of allowlist entries.
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.

List allowlist or look up an address

Three answers from one route.

GET/v1/suppressionscope · read

import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.suppression.list({
  limit: 10,
});
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.list_suppression(limit=10)
print(result)

curl 'https://api.mails.ai/v1/suppression?limit=10' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails suppressions list
mails suppressions list --address jordan@example.com

{
  "name": "mails_suppressions_list",
  "arguments": { "limit": 10 }
}

{
  "suppressed": false,
  "type": "hard_bounce",
  "scope": "<scope>",
  "since": "2026-10-04T12:00:00.000Z",
  "allowed": {
    "id": "sup_01JZX8K3M9Q4P7VN2YB6RTDC0E",
    "attestation": "<attestation>",
    "created_at": "<created_at>"
  }
}

200  A suppression lookup (when address is set), your
     suppressed recipients (when view=suppressed), or a
     page of allowlist entries.
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.

Query Parameters

addressstring

Look up suppression status for this address instead of listing the allowlist.

viewstring

suppressed: list which of your own recent recipients are suppressed for you, and why, instead of the allowlist.

One of: suppressed

limitinteger

Page size (1–100).

Default: 25

cursorstring

Opaque cursor from a previous page's next_cursor.

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).

Was this page helpful?