Email suppressions API

Manage addresses that must not receive outgoing support email from your workspace.

Admin access

These dashboard endpoints require an authenticated agent session JWT in Authorization: Bearer. A Verify, messaging, or MCP connection key does not grant access to them. Requests stay within the authenticated workspace.

All suppression routes require admin access. Email suppression is separate from SMS and iMessage STOP handling.

Read the suppression list

GET /api/v1/suppressions accepts limit (default 50, maximum 200) and cursor (the ISO timestamp from nextCursor). The response is { entries: [...], nextCursor: string | null }. Entries include id, email, reason, addedAt, addedByAgentId, addedByAgentName, sourceMessageId and note. Results are newest first. There are no reason or email-prefix query filters.

Read the suppression list

curl 'https://app.message.com/api/v1/suppressions?limit=50' \
  -H 'Authorization: Bearer YOUR_AGENT_JWT'

Add an address

POST /api/v1/suppressions accepts email, optional reason and optional note (up to 500 characters). The address is trimmed and lowercased. reason defaults to manual; other accepted values are hard_bounce, complaint and soft_bounce_exceeded. Use manual for an administrator’s action. The response is HTTP 200 with { ok: true, added: boolean, email }. An existing suppression returns added: false rather than a duplicate error.

Add an address

curl 'https://app.message.com/api/v1/suppressions' \
  -H 'Authorization: Bearer YOUR_AGENT_JWT' \
  -H 'Content-Type: application/json' \
  --data '{"email":"[email protected]","reason":"manual","note":"Customer requested no further email"}'

Remove an address

DELETE /api/v1/suppressions/:id returns HTTP 204 when removed. A missing entry returns 404 not_found; an invalid ID returns 400 invalid_id. Removing a suppression permits future delivery attempts. Do so only when the underlying reason has been resolved and the recipient may be contacted.

Automatic delivery protection

Permanent delivery failures and spam complaints also populate the list. Outbound email checks the suppression list before sending. A successful API removal does not make an invalid mailbox deliverable.