Add Suppressions API support (add + list + get + remove + batch)

[felipefreitag]

What

Adds suppression-list support to IResend / ResendClient: SuppressionAddAsync, SuppressionListAsync, SuppressionRetrieveAsync, SuppressionRemoveAsync, SuppressionBatchAddAsync, SuppressionBatchRemoveAsync — all returning ResendResponse<T> and taking a CancellationToken.

Follows the Domain Claims PR (#133) for structure: partial class ResendClient.Suppressions.cs, models in src/Resend, request objects under Payloads, and the existing JsonStringEnumValueConverter + [JsonStringValue] pattern for SuppressionOrigin (as DomainClaimStatus does). Reuses the existing PaginatedResult<T> for has_more/data.

Details worth calling out:

• SuppressionRetrieveAsync/SuppressionRemoveAsync take a string, not a Guid, because the path parameter accepts an ID or an email address (the server does validator.isUUID() and treats a non-UUID as an email). Escaped with Uri.EscapeDataString.
• Batch remove is expressed as two overloads — IEnumerable<string> emails and IEnumerable<Guid> suppressionIds — which makes the emails-XOR-ids constraint a compile-time guarantee rather than a runtime check. Both payload properties use JsonIgnoreCondition.WhenWritingNull so the unset one is omitted.
• SuppressionSummary (list entries) and Suppression (get) are separate types, differing only by Object.
• source_id is typed string?, not Guid?: the underlying column is free-text and the spec declares a plain string, so a non-UUID value would otherwise throw and discard an entire list page. Id stays Guid, which the schema does back.

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

dotnet build   -> 0 Errors
dotnet test    -> 173 passed (158 Resend.Tests + 11 Webhooks + 4 FluentEmail), 0 failed

Run on the .NET 8 SDK to match CI (dotnet-version: 8.0.x) and the net8.0 target. Worth knowing for anyone reproducing locally: on a machine with only the .NET 10 runtime installed, dotnet test aborts outright, and forcing DOTNET_ROLL_FORWARD=Major yields ~61 spurious failures out of 131 on unmodified main — so a .NET 8 runtime is required for a meaningful run.

Tests cover all six operations plus null source_id, a non-UUID source_id on both the single and list shapes, and the real Postgres-style created_at format the API actually emits (2026-07-24 18:30:00.123456+00) rather than only the ISO form shown in the docs.

---

Summary by cubic

Adds Suppressions API support to the .NET client for add, list, get, remove, and batch operations to manage suppressed emails. Matches server behavior and edge cases.

• New Features

  • Methods: SuppressionAddAsync, SuppressionListAsync, SuppressionRetrieveAsync, SuppressionRemoveAsync, SuppressionBatchAddAsync, SuppressionBatchRemoveAsync.
  • SuppressionRetrieveAsync/SuppressionRemoveAsync accept an ID or an email (string). Input is URL-encoded; blank values throw ArgumentException.
  • Separate models for single vs list: Suppression (has object) and SuppressionSummary (no object).
  • source_id is string? to allow non-UUID values; Id remains Guid.
  • Batch remove has two overloads (emails or ids). The unset field is omitted in the payload to satisfy the XOR rule.
  • Batch responses can be shorter than inputs (email dedupe; remove returns only deleted). Do not pair results to inputs by index.
  • List supports pagination and optional origin filter. Endpoints may return 404 for teams without the feature flag.

• Bug Fixes

  • Mock server: reject null/blank entries in suppression batches with 422 (not 500), matching API validation and preventing silent drops.
  • Enum JSON handling: allow aliases and throw on conflicting wire values; share wire mapping via JsonStringEnumValue<T> and use it for the origin query.

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

[cubic-dev-ai]

All reported issues were addressed across 13 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 6 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Confidence score: 4/5

• In tools/Resend.ApiServer/Controllers/SuppressionController.cs, ValidateEmails only checks for null/whitespace, so batch add/remove can accept malformed addresses like not-an-email, which can pollute suppression data and create inconsistent behavior versus the API’s single-email validation. Reuse the same email-format validator for batch inputs (and add a malformed-email test case) to de-risk this path.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="tools/Resend.ApiServer/Controllers/SuppressionController.cs">

<violation number="1" location="tools/Resend.ApiServer/Controllers/SuppressionController.cs:152">
P2: Batch add/remove accept malformed email strings such as `not-an-email`; `ValidateEmails` checks only null/whitespace and never validates email syntax. Using the same email-format validation as the API, with a malformed-address test, would keep the mock behavior aligned with its stated contract.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Batch add/remove accept malformed email strings such as not-an-email; ValidateEmails checks only null/whitespace and never validates email syntax. Using the same email-format validation as the API, with a malformed-address test, would keep the mock behavior aligned with its stated contract.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At tools/Resend.ApiServer/Controllers/SuppressionController.cs, line 152:

<comment>Batch add/remove accept malformed email strings such as `not-an-email`; `ValidateEmails` checks only null/whitespace and never validates email syntax. Using the same email-format validation as the API, with a malformed-address test, would keep the mock behavior aligned with its stated contract.</comment>

<file context>
@@ -129,6 +143,24 @@ public ActionResult<ListOf<SuppressionRemoveResult>> SuppressionBatchRemove( [Fr
+    /// </summary>
+    private ActionResult? ValidateEmails( IEnumerable<string>? emails )
+    {
+        if ( emails != null && emails.Any( x => string.IsNullOrWhiteSpace( x ) ) == false )
+            return null;
+
</file context>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

Confidence score: 5/5

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

<sub>Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.

Re-trigger cubic</sub>