POST/api/v1/projects/{project_id}/suppressions

`add_suppression`

Suppresses an address by hand (reason manual) for the project or one of its lists: it gets no mail of that scope; subscriber statuses are not changed.

Call it: when an address must not be mailed whatever list it is on.
Needs: an admin key with project_id, or a project key with scope write (its own project; the argument is ignored), and confirm: true; without it the call changes nothing and tells what it would do.
Returns: outcome (would_add, added, already_suppressed), effect in words and the suppression as POST /api/v1/projects/{project_id}/suppressions answers it (null in a dry run of a new one).

Arguments

object
emailstringrequired

The address; any case and surrounding whitespace are normalized.

example ann@example.com
scopestringrequired

project (every list) or list:<list_id> (one list of the project).

example project
confirmboolean

true suppresses the address. Without it the call only tells what would happen and changes nothing.

default false
project_idstring · uuid | null

The project. An admin key must pass it; a project key’s own project is used and this is ignored.
reasonstring

manual, the only reason a caller gives (left out: the same).

example manual

No other arguments are accepted.

Result

The result comes back as structuredContent, with the same JSON as a text block.

object · all fields required
effectstring

The outcome in words, for the agent and its user.
outcomeAdditionOutcome

What an addition did.

would_add A dry run: nothing changed; a call with confirm: true suppresses.

added Suppressed now.

already_suppressed Suppressed for the scope before; nothing changed.
suppressionSuppression | null

The suppression as the API’s POST answers it (201 added, 200 already suppressed); null in a dry run of a new one.
6 fields
- Suppression object · all fields required
- created_atstring · date-time
- emailstring · email
- project_idstring · uuid
  
  The suppression’s project.
- reasonstring
  
  unsubscribed_all, unsubscribed_list, hard_bounce, soft_bounce_limit, complaint or manual.
- scopestring
  
  project (every list) or list:<list_id>.
- sourcestring
  
  Where it came from: api (the API or MCP), web, delivery or inbound.

Definitions

AdditionOutcome

What an addition did.

string · enum

would_add A dry run: nothing changed; a call with confirm: true suppresses.

added Suppressed now.

already_suppressed Suppressed for the scope before; nothing changed.

Suppression

An address on the project’s suppression list (GET /api/v1/projects/{project_id}/suppressions, an item).

object · all fields required
created_atstring · date-time
emailstring · email
project_idstring · uuid

The suppression’s project.
reasonstring

unsubscribed_all, unsubscribed_list, hard_bounce, soft_bounce_limit, complaint or manual.
scopestring

project (every list) or list:<list_id>.
sourcestring

Where it came from: api (the API or MCP), web, delivery or inbound.

Errors

A failed call answers isError: true with a code from the same table as the HTTP API, and detail. How tools report errors

HTTP API

The same operation over HTTP: POST /api/v1/projects/{project_id}/suppressions