feat: add suppressions endpoints

[felipefreitag]

What

Adds suppression-list support: add, list, get, remove, plus a nested Batch with add / remove — each with an _async twin (6 sync + 6 async).

Follows the resend/domains/claims/ layout for a nested sub-resource, reuses PaginationHelper for list, Literal for the origin enum, and urllib.parse.quote(..., safe='') for the id-or-email path segment.

resend.Suppressions.add({"email": "..."})
resend.Suppressions.list({"origin": "manual", "limit": 10})
resend.Suppressions.get(id_or_email)
resend.Suppressions.remove(id_or_email)
resend.Suppressions.Batch.add({"emails": [...]})
resend.Suppressions.Batch.remove({"emails": [...]})   # or {"ids": [...]}

Two TypedDicts rather than one: SuppressionListItem (five fields) for list entries and Suppression for get (those five plus object) — following the existing Event / EventListItem precedent in resend/events/_event.py, which is the same situation.

Batch.remove builds its body through a single _build_remove_body helper that both validates the XOR and strips None values, so validation and serialization cannot disagree about what None means — matching the # Filter out None values convention already in PaginationHelper.

Contract verification

Verified in order of authority: the API server implementation (apps/public-api/src/routes/suppressions/ in the monorepo), then resend-openapi resend.yaml, then the docs — and finally end-to-end against the live API with a real team key (read-only operations).

One deliberate divergence, flagged so it does not look like a bug in review: list entries do not carry the object field; only the single-get response does. list.ts selects exactly {id, email, origin, source_id, created_at} and adds nothing, while get.ts returns {object: "suppression", ...}. Confirmed on live wire output.

Two upstream artifacts disagree with the server here and are being tracked separately, so please do not use them as the reference when reviewing:

• the list-suppressions docs example shows a per-entry object that the API never sends
• resend-node SuppressionListEntry declares the same nonexistent field, and is shipped in resend@6.18.0

The OpenAPI spec is correct on this point and agrees with the implementation.

Other behaviour confirmed at the server and reflected in docs/tests, not reimplemented client-side:

• batch/remove accepts emails XOR ids; the unset key must be omitted, since the server validation accepts undefined but rejects an explicit null
• the API lowercases, trims and deduplicates emails, and batch/add upserts — so batch responses can contain fewer entries than were sent; callers must not pair results to inputs by index
• batch/remove returns only rows actually deleted (misses are absent, no error), whereas single remove returns 404 on a miss
• source_id is nullable and is null for manual-origin suppressions

Release timing

These endpoints are in beta and gated behind a server-side feature flag: a team without access receives 404 on every suppression endpoint. Merging is safe, but worth a deliberate decision on whether this ships in the next release or waits for wider flag rollout, since otherwise a documented SDK method returns 404 for most users.

Verification

tox -e lint   -> OK (flake8)
tox -e mypy   -> Success: no issues found in 176 source files
tox -e py     -> 552 passed

Python 3.9.6, inside CI's 3.8-3.11 matrix. 58 of those tests cover suppressions, including null source_id, the ids batch-remove variant, explicit-None omission (sync and async), server-side dedupe returning fewer entries than sent, and the all-miss empty-data case.

---

Summary by cubic

Adds suppression list support to the resend Python SDK. Includes add, list, get, remove, and batch add/remove with both sync and async methods.

• New Features

  • Suppressions.add, list, get, remove, plus Suppressions.Batch.add and remove (async variants included).
  • Typed responses: Suppression (single), SuppressionListItem (list), and SuppressionOrigin enum.
  • Pagination via limit/after/before; built with PaginationHelper.
  • Lookups accept ID or email; emails are URL-encoded safely.
  • New usage examples added for sync and async.

• Migration

  • Endpoints are feature-flagged; teams without access will get 404. Handle or gate these calls.
  • For batch/remove, send either emails or ids (not both) and omit the unset key (do not send null).
  • List entries do not include an object field; only get responses do.
  • Batch responses may return fewer items than sent due to normalization/deduping; do not match results to inputs by index.

^{Written for commit 2155f03. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 11 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}