# Suppressions API

An address may appear once per scope target. Team blocks apply on every send; project blocks apply to all routes in that project; route blocks apply to one route.

Hard bounces and complaints auto-suppress at **team** scope. One-click list-unsubscribe suppresses at **route** scope when the message had a route. Soft bounces do not suppress.

## Nested (recommended)

```bash
# list — filters: reason, scope, project_id, route_id, q, start, end, limit
curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/practices/$PRACTICE_ID/suppression?scope=route&route_id=$ROUTE_ID&limit=500"

# add
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"emails":["bad@example.com"],"reason":"manual","scope":"team"}' \
  "$BASE/api/practices/$PRACTICE_ID/suppression"

curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"u@example.com","reason":"unsubscribe","scope":"route","route":"broadcast"}' \
  "$BASE/api/practices/$PRACTICE_ID/suppression"
```

Reasons: `manual`, `unsubscribe`, `hard_bounce` / `bounce`, `spam_complaint` / `complaint`.

## Import / export / delete

```bash
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -F "file=@suppressions.csv" \
  "$BASE/api/practices/$PRACTICE_ID/suppression/import?default_reason=hard_bounce&default_scope=team"

curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/practices/$PRACTICE_ID/suppression/export?include_source=true" \
  -o suppressions.csv

curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["'"$SUPPRESSION_ID"'"]}' \
  "$BASE/api/practices/$PRACTICE_ID/suppression/bulk-delete"

curl -sS -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/practices/$PRACTICE_ID/suppression/$SUPPRESSION_ID"
```

CSV columns: `email` / `address`, optional `reason`, `scope`, `project`, `route`. Export adds `created_at` and optional `source_event`.

Bulk delete max **1000** ids.

## Flat aliases

`GET|POST /api/suppressions` and `DELETE /api/suppressions/{id}` require `project_id` (workspace id) as query or body. Manual creates default to the nested default project so every row has an explicit project reference.