API reference

Suppressions

The suppression list holds the addresses and domains that anymail never emails. The one-click unsubscribe link writes to the same list. The engine checks the list on every send attempt, without a cache.

Method Path Action
POST /api/v1/suppressions Exclude an address or a domain
GET /api/v1/suppressions List the suppression list of the workspace
DELETE /api/v1/suppressions/{id} Remove an entry

Exclude an address or a domain#

The endpoint honours an Idempotency-Key.

Body (JSON, up to 4 KiB)

Field Type Required Notes
target string Yes An email address such as jane@example.com, or a bare domain such as example.com. 
curl -X POST "https://app.anymail.watch/api/v1/suppressions" \
  -H "Authorization: Bearer $ANYMAIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com"}'

Response 201

{ "id": "d5e6f7a8-0000-4000-8000-000000000001", "kind": "domain", "value": "example.com" }

kind is email or domain. value is the normalised target.

Errors

Status Message
400 The body errors listed on Errors.
400 `target` must be a non-empty string — an email address or a domain.
400 `target` is not a valid email address or domain (e.g. acme.com).
409 <value> is already excluded. The body has "code": "duplicate", kind and value. The target is already unreachable, so the goal is met.
500 Couldn't exclude it: <message>

List suppressions#

Parameter Type Notes
kind string email or domain.
limit integer 1 to 100. Default 50.
cursor string See Pagination. 
curl "https://app.anymail.watch/api/v1/suppressions?kind=email" \
  -H "Authorization: Bearer $ANYMAIL_TOKEN"

Response 200

{
  "data": [
    {
      "id": "d5e6f7a8-0000-4000-8000-000000000002",
      "kind": "email",
      "value": "jane@example.com",
      "reason": "Excluded via the API.",
      "created_at": "2026-09-03T00:00:00.000+00:00"
    }
  ],
  "next_cursor": null
}

The list shows only the suppressions of the workspace. The global anymail list, which also applies when you send, is not visible through the API.

Remove a suppression#

DELETE /api/v1/suppressions/{id} does what Remove does in Settings, Suppressions. The response is 204 with no body.

curl -X DELETE "https://app.anymail.watch/api/v1/suppressions/d5e6f7a8-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $ANYMAIL_TOKEN"

The engine reads the list on every send attempt, so the address is reachable from the next attempt. Enrolments that stopped earlier because of the suppression are not revived, as after a click in the app.

Errors: 404 with {"error":"Suppression not found."} for an unknown id, an id from another workspace, an id that is not a UUID and an id from the global list.