Suppress an address

Adds the address to the project’s suppression list by hand (reason manual), for the project or one list: it gets no mail of that scope. Subscriber statuses are not changed. Needs scope write. An address already suppressed for the scope keeps its suppression: 200.

Parameters

Name	In	Type	Description
`project_id`required	path	string · uuid	The project’s id
`Idempotency-Key`	header	string 1–128 characters · pattern `^[!-~]{1,128}$`	A key of the client’s choosing, one per request it means to send once (a UUID will do). A repeat with the same key and the same body within 24 h creates nothing again and gets the first answer, marked `Idempotent-Replayed: true`. The key belongs to the API key that sent it. Only a `2xx` answer is kept: after any other answer the key is free again.

Request body

application/json · required

CreateSuppressionRequest object
emailstring · emailrequired

The address; any case and surrounding whitespace are normalized.

example ann@example.com
scopestringrequired

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

example project
reasonstring | null

manual, the only reason a client gives (the default).

example manual

Responses

200

The address was suppressed for the scope already; nothing changed

Header	Type	Description
`Idempotent-Replayed`	string · enum	`true` when the answer is a replay of an earlier request with the same `Idempotency-Key`; absent otherwise.

Suppression object · all fields required
created_atstring · date-time
emailstring · email

example ann@example.com
project_idstring · uuid

The suppression’s project.
reasonstring

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

example manual
scopestring

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

example project
sourcestring

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

example api

201

The address is suppressed

Header	Type	Description
`Idempotent-Replayed`	string · enum	`true` when the answer is a replay of an earlier request with the same `Idempotency-Key`; absent otherwise.
`Location`	string	Where `DELETE` removes this suppression

Suppression object · all fields required
created_atstring · date-time
emailstring · email

example ann@example.com
project_idstring · uuid

The suppression’s project.
reasonstring

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

example manual
scopestring

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

example project
sourcestring

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

example api

400

Not JSON (invalid_json)

Problem (application/problem+json)

401

No valid key

Problem (application/problem+json)

403

A project key without scope write (forbidden)

Problem (application/problem+json)

404

No such project, or another project (not_found)

Problem (application/problem+json)

409

The project is deleted (conflict); or a request with the same Idempotency-Key has not answered yet (idempotency_key_in_progress)

Problem (application/problem+json)

413

Over 10 MB (body_too_large)

Problem (application/problem+json)

415

Not application/json (unsupported_media_type)

Problem (application/problem+json)

422

Invalid fields, every one in errors (validation_failed): a bad email, a scope that is not project or a list of this project, a reason other than manual; or the Idempotency-Key was used in the last 24 h for another request (idempotency_key_reused), or is not 1 to 128 visible ASCII characters (validation_failed, field Idempotency-Key)

Problem (application/problem+json)

429

The key is over its rate limit, api.rate_limit_per_minute requests a minute on this node (rate_limited)

Header	Type	Description
`Retry-After`	integer	Seconds until the key’s next request passes; rounded up.

Problem (application/problem+json)

504

Postwind’s storage did not answer within its time limit (storage_timeout). A change the request makes may still take effect: check before repeating it. A repeat with the same Idempotency-Key never runs it twice: it is 409 idempotency_key_in_progress until the key’s 24 h end

Problem (application/problem+json)