Suppression

The suppression list is a per-workspace set of email addresses that must never be sent to — unsubscribes, bounces, and manually added addresses. It's checked automatically across campaigns and the lead export/push endpoints; this API is for managing the list directly.

All endpoints below require X-Api-Key. They are not project-scoped — the list applies to your entire active workspace (the one currently selected on your account, the same as the dashboard), not a single project.

The suppression row

{
  "id": "d4a2f6e1-7c3b-4e9a-8b1d-5f2c9a3e6b7c",
  "email": "unsubscribed@example.com",
  "reason": "unsubscribed",
  "createdAt": "2026-07-15T12:03:00.000Z"
}

reason is one of unsubscribed, bounced, or manual. unsubscribed and bounced are set automatically by Warmerly (the unsubscribe link and bounce classifier, respectively) — addresses added through this API's POST endpoint are always recorded as manual.

List suppressed addresses

GET /suppression

Query param	Type	Required	Description
`search`	string	No	Case-insensitive substring match on email.
`reason`	`"unsubscribed"` \| `"bounced"` \| `"manual"`	No	Filter to one reason.
`limit`	integer	No	Page size, 1–1000. Default `50`.
`offset`	integer	No	Page offset. Default `0`.
`order`	`"newest"` \| `"email"`	No	Sort order. Default `newest`.
`format`	`"csv"`	No	If set to `csv`, returns a CSV download instead of JSON (ignores `limit`/`offset`/`order` and returns every row — see Export as CSV).

curl "https://app.warmerly.com/api/v1/suppression?reason=bounced&limit=25" \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "rows": [
    {
      "id": "d4a2f6e1-7c3b-4e9a-8b1d-5f2c9a3e6b7c",
      "email": "bounced@example.com",
      "reason": "bounced",
      "createdAt": "2026-07-15T12:03:00.000Z"
    }
  ],
  "total": 214
}

Export as CSV

curl "https://app.warmerly.com/api/v1/suppression?format=csv" \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -o suppression-list.csv

Returns every row in the workspace (not paginated) as content-type: text/csv, columns email,reason,added_at.

Add addresses

POST /suppression

Field	Type	Required	Description
`emails`	string (1–1,000,000 chars)	Yes	A blob of addresses separated by commas, semicolons, tabs, or newlines. Tolerates `Name <a@b.com>` formatting and a leading `email`/`email_address` CSV header — paste a raw CSV column unedited.

Every address added this way is recorded with reason: "manual". Up to 5,000 addresses can be added in a single request.

curl -X POST https://app.warmerly.com/api/v1/suppression \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "emails": "jane@example.com, john@example.com" }'

201 Created:

{ "added": 2, "alreadyPresent": 0, "invalid": [] }

added is new rows inserted; alreadyPresent is addresses already on the list (idempotent — re-adding one is a no-op); invalid lists tokens that looked like an email attempt (contained @) but failed validation.

Errors: 400 bad_request with message: "no_valid_emails" if nothing in emails parses as a valid address, or message: "too_many_emails" (with details: { max, received }) if the parsed list exceeds 5,000.

Remove addresses

DELETE /suppression

Field	Type	Required	Description
`ids`	string[] (UUID, 1–1000)	Yes	Row IDs to remove, from the `id` field returned by List.

curl -X DELETE https://app.warmerly.com/api/v1/suppression \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["d4a2f6e1-7c3b-4e9a-8b1d-5f2c9a3e6b7c"] }'

{ "removed": 1 }

IDs that don't exist or belong to another workspace are silently ignored — removed reflects only rows that actually matched and were deleted. 400 bad_request if ids is missing, empty, or not valid UUIDs.

Every add/remove call is recorded in the workspace audit log (suppression.added / suppression.removed).