Suppressions

List suppressed addresses

GET/api/v1/suppressions

GET /suppressions
curl -X GET 'https://www.unitpost.com/api/v1/suppressions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "suppression",
      "id": "id_123",
      "email": "customer@example.com",
      "scope": "workspace",
      "reason": "bounce",
      "detail": "string",
      "note": "string",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of the email addresses your workspace has suppressed, newest-first and cursor-paginated. The list holds your workspace's own suppressions only. Unitpost-wide (platform) blocks are enforced at send time but never listed: they appear as email.suppressed on the send they stopped, and Retrieve a suppressed address with an email address still returns one, so you can see why that address is blocked. (Since 2026-10-13; before that the list also included platform rows.) Add an address with Suppress an address or lift a block with Un-suppress an address. Narrow the list with q, reason and a created_after / created_before range. A filter value it can't apply (a typo, an unknown id) is ignored and named in the Unitpost-Warning header, and the answer is the one without it; send Unitpost-Strict: true to have it refused instead. Requires the suppressions:read capability.

Parameters8 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
qstring · queryPart of the email address (case-insensitive). At most 200 characters.
reasonstring · queryOnly suppressions with this reason.
created_afterstring · queryOnly suppressions created at or after this time. ISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time).
created_beforestring · queryOnly suppressions created before this time. ISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time).
scopestring · queryDeprecated and ignored (2026-10-13). The list always returns your workspace's own suppressions; platform rows are never listed. Still accepted so existing callers don't break.
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring—
scoperequiredenumworkspace | platform—
reasonrequiredenumbounce | complaint | unsubscribe | manual | import | api—
detailrequiredstring | null—
noterequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403422

Suppress an address

POST/api/v1/suppressions

POST /suppressions
curl -X POST 'https://www.unitpost.com/api/v1/suppressions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "suppression",
  "id": "id_123",
  "email": "customer@example.com",
  "scope": "workspace",
  "reason": "bounce",
  "detail": "string",
  "note": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Block one address ({ email }) or up to 1,000 at once ({ emails: [...] }) from receiving any future sends from your workspace. The operation is idempotent — re-suppressing an existing address returns 200 rather than a conflict. The bulk form returns an { object: "list", added, skipped, total } summary. Suppression is the hard stop; to let recipients opt out of just one kind of email, use topics (see Create a topic). Undo with Un-suppress an address. Requires the suppressions:write capability.

Request body4 fields
FieldTypeDescription
emailstring—
emailsstring[]—
reasonenummanual | import | api—
notestring—
200201401403422

Retrieve a suppressed address

GET/api/v1/suppressions/{id}

GET /suppressions/{id}
curl -X GET 'https://www.unitpost.com/api/v1/suppressions/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "suppression",
  "id": "id_123",
  "email": "customer@example.com",
  "scope": "workspace",
  "reason": "bounce",
  "detail": "string",
  "note": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve one suppression by id (supp_…) or by the email address itself. Returns your own workspace row, or a read-only platform row when the address is blocked Unitpost-wide. Lift a workspace block with Un-suppress an address. Requires the suppressions:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · pathA suppression id (`supp_…`) or the email address.
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring—
scoperequiredenumworkspace | platform—
reasonrequiredenumbounce | complaint | unsubscribe | manual | import | api—
detailrequiredstring | null—
noterequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404

Un-suppress an address

DELETE/api/v1/suppressions/{id}

DELETE /suppressions/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/suppressions/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Remove a workspace suppression by id or email so the address can receive your mail again. The email form is idempotent — removing an address that isn't suppressed still returns 204. Unitpost-wide (platform) entries can't be removed here (403) — contact support. Check what's blocking an address first with Retrieve a suppressed address. Requires the suppressions:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · pathA suppression id (`supp_…`) or the email address.
204401403404

Search docs and guides

Search the docs and product guides.