feat: add suppression endpoints support

Author: CarolinaMoraes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "resend-cli",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "description": "The official CLI for Resend",
   "license": "MIT",
   "repository": {
@@ -46,7 +46,7 @@
     "esbuild": "0.28.1",
     "esbuild-wasm": "0.28.0",
     "picocolors": "1.1.1",
-    "resend": "6.17.1"
+    "resend": "6.18.0-canary.0"
   },
   "pkg": {
     "scripts": [

pnpm-lock.yaml

@@ -13,7 +13,7 @@ metadata:
   author: resend
   # Skill version is independent from the CLI/package.json version —
   # bump it on skill content changes, not CLI releases.
-  version: "2.3.1"
+  version: "2.4.0"
   homepage: https://resend.com/docs/cli-agents
   source: https://github.com/resend/resend-cli
   openclaw:
@@ -57,6 +57,7 @@ references:
   - references/templates.md
   - references/topics.md
   - references/logs.md
+  - references/suppressions.md
   - references/webhooks.md
   - references/auth.md
   - references/workflows.md
@@ -143,6 +144,7 @@ Auth resolves: `--api-key` flag > `RESEND_API_KEY` env > config file (`resend lo
 | `emails receiving` | list, get, attachments, forward, listen |
 | `domains` | create, verify, get, claim, update, delete, list |
 | `logs` | list, get, open |
+| `suppressions` _(beta)_ | list, add, get, delete, batch — requires account enrollment |
 | `api-keys` | create, list, delete |
 | `automations` | create, get, list, update, delete, stop, open, runs |
 | `events` | create, get, list, update, delete, send, open |
@@ -220,6 +222,7 @@ resend doctor -q
 - **Defining contact properties** → [references/contact-properties.md](references/contact-properties.md)
 - **Working with templates** → [references/templates.md](references/templates.md)
 - **Viewing API request logs** → [references/logs.md](references/logs.md)
+- **Managing the suppression list** (beta) → [references/suppressions.md](references/suppressions.md)
 - **Creating automations or sending events** → [references/automations.md](references/automations.md)
 - **Setting up webhooks or listening for events** → [references/webhooks.md](references/webhooks.md)
 - **Auth, profiles, or health checks** → [references/auth.md](references/auth.md)

skills/resend-cli/SKILL.md

@@ -0,0 +1,101 @@
+# suppressions
+
+Detailed flag specifications for `resend suppressions` commands.
+
+> **Beta:** Suppressions is a pre-GA feature gated per account. Commands appear in
+> `--help` but return an API error unless the suppression list is enabled for your
+> account. Reach out to Resend to join the beta.
+
+Suppressions block future sends to an address. Each entry has an `origin`:
+
+| Origin | Meaning |
+|--------|---------|
+| `bounce` | Added automatically after a hard bounce |
+| `complaint` | Added automatically after a spam complaint |
+| `manual` | Added by you via `suppressions add` |
+
+`get` and `delete` accept **either** a suppression ID **or** the email address.
+
+---
+
+## suppressions list
+
+List suppressed addresses (default subcommand — `resend suppressions` alone runs it).
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--limit <n>` | number | No | Max results, 1-100 (default 10) |
+| `--after <cursor>` | string | No | Forward pagination cursor |
+| `--before <cursor>` | string | No | Backward pagination cursor |
+| `--origin <origin>` | string | No | Filter: `bounce` \| `complaint` \| `manual` |
+
+**Alias:** `ls`
+
+**Output:** `{"object":"list","has_more":false,"data":[{"object":"suppression","id":"...","email":"...","origin":"bounce|complaint|manual","source_id":"..."|null,"created_at":"..."}]}`
+
+---
+
+## suppressions add
+
+Suppress a single email address (origin `manual`).
+
+**Argument:** `<email>` — email address to suppress (required in non-interactive mode)
+
+**Output:** `{"object":"suppression","id":"..."}`
+
+---
+
+## suppressions get
+
+Retrieve a single suppression.
+
+**Argument:** `<id-or-email>` — suppression ID or the suppressed email address
+
+**Output:** `{"object":"suppression","id":"...","email":"...","origin":"...","source_id":"..."|null,"created_at":"..."}`
+
+---
+
+## suppressions delete
+
+Remove a suppression so Resend can send to the address again.
+
+**Argument:** `<id-or-email>` — suppression ID or the suppressed email address
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--yes` | boolean | Yes (non-interactive) | Skip confirmation |
+
+**Alias:** `rm`
+
+**Output:** `{"object":"suppression","id":"...","deleted":true}`
+
+---
+
+## suppressions batch add
+
+Suppress up to 100 addresses in one request.
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--file <path>` | string | Yes (non-interactive) | JSON file with an array of email strings (`-` for stdin) |
+
+**File format:** `["a@example.com", "b@example.com"]`
+
+**Output:** `{"data":[{"object":"suppression","id":"..."}]}`
+
+---
+
+## suppressions batch remove
+
+Remove up to 100 suppressions in one request.
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--file <path>` | string | Yes (non-interactive) | JSON file with an array of strings (`-` for stdin) |
+| `--ids` | boolean | No | Treat file entries as suppression IDs instead of emails |
+
+**Alias:** `rm`
+
+**File format:** `["a@example.com", "b@example.com"]` (or IDs with `--ids`)
+
+**Output:** `{"data":[{"object":"suppression","id":"...","deleted":true}]}`

skills/resend-cli/references/suppressions.md

@@ -20,6 +20,7 @@ import { logsCommand } from './commands/logs/index';
 import { oauthGrantsCommand } from './commands/oauth-grants/index';
 import { openCommand } from './commands/open';
 import { segmentsCommand } from './commands/segments/index';
+import { suppressionsCommand } from './commands/suppressions/index';
 import { templatesCommand } from './commands/templates/index';
 import { topicsCommand } from './commands/topics/index';
 import { updateCommand } from './commands/update';
@@ -140,6 +141,9 @@ ${pc.gray('Examples:')}
   .addCommand(topicsCommand)
   .addCommand(domainsCommand)
   .addCommand(logsCommand)
+  // Visible pre-GA with a [beta] marker in its description — the API gates usage
+  // per account, so non-enabled users see the command but get an API error until enrolled.
+  .addCommand(suppressionsCommand)
   .addCommand(apiKeysCommand)
   .addCommand(webhooksCommand)
   .addCommand(oauthGrantsCommand)

src/cli.ts

@@ -0,0 +1,50 @@
+import { Command } from '@commander-js/extra-typings';
+import pc from 'picocolors';
+import { runCreate } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import { requireText } from '../../lib/prompts';
+
+export const addSuppressionCommand = new Command('add')
+  .description('Suppress an email address so it stops receiving your emails')
+  .argument('[email]', 'Email address to suppress')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `Non-interactive: <email> is required (no prompts when stdin/stdout is not a TTY).
+
+A suppressed address is skipped on future sends. Added this way, the entry has
+origin "manual". Use "suppressions delete" to remove it again.`,
+      output: `  {"object":"suppression","id":"<id>"}`,
+      errorCodes: ['auth_error', 'missing_email', 'create_error'],
+      examples: [
+        'resend suppressions add spam@example.com',
+        'resend suppressions add spam@example.com --json',
+      ],
+    }),
+  )
+  .action(async (emailArg, _opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+
+    const email = await requireText(
+      emailArg,
+      { message: 'Email to suppress', placeholder: 'e.g. spam@example.com' },
+      {
+        message: 'Missing <email> argument.',
+        code: 'missing_email',
+      },
+      globalOpts,
+    );
+
+    await runCreate(
+      {
+        loading: 'Suppressing address...',
+        sdkCall: (resend) => resend.suppressions.add({ email }),
+        onInteractive: (d) => {
+          console.log(`  ${pc.gray('Email:')}  ${email}`);
+          console.log(`  ${pc.gray('ID:')}     ${d.id}`);
+        },
+      },
+      globalOpts,
+    );
+  });

src/commands/suppressions/add.ts

@@ -0,0 +1,85 @@
+import { Command } from '@commander-js/extra-typings';
+import type { GlobalOpts } from '../../../lib/client';
+import { requireClient } from '../../../lib/client';
+import { readFile } from '../../../lib/files';
+import { buildHelpText } from '../../../lib/help-text';
+import { outputResult } from '../../../lib/output';
+import { requireText } from '../../../lib/prompts';
+import { withSpinner } from '../../../lib/spinner';
+import { isInteractive } from '../../../lib/tty';
+import { readEmailList } from './utils';
+
+export const batchAddSuppressionsCommand = new Command('add')
+  .description(
+    'Suppress up to 100 email addresses from a JSON file in one request',
+  )
+  .option(
+    '--file <path>',
+    'Path to a JSON file containing an array of email strings (use "-" for stdin; required in non-interactive mode)',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `Non-interactive: --file
+Limit: 100 emails per request (API hard limit — warned if exceeded)
+
+File format (--file path):
+  ["spam@example.com", "bounce@example.com"]`,
+      output: `  {"data":[{"object":"suppression","id":"<id>"}]}`,
+      errorCodes: [
+        'auth_error',
+        'missing_file',
+        'file_read_error',
+        'stdin_read_error',
+        'invalid_json',
+        'invalid_format',
+        'create_error',
+      ],
+      examples: [
+        'resend suppressions batch add --file ./emails.json',
+        'echo \'["a@example.com","b@example.com"]\' | resend suppressions batch add --file -',
+      ],
+    }),
+  )
+  .action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    const resend = await requireClient(globalOpts);
+
+    const filePath = await requireText(
+      opts.file,
+      { message: 'Path to JSON file', placeholder: './emails.json' },
+      {
+        message:
+          'Missing --file flag. Provide a JSON file with an array of email strings.',
+        code: 'missing_file',
+      },
+      globalOpts,
+    );
+
+    const raw = readFile(filePath, globalOpts);
+    const emails = readEmailList(raw, globalOpts);
+
+    if (emails.length > 100) {
+      console.warn(
+        `Warning: ${emails.length} emails exceeds the 100-email limit. The API may reject this request.`,
+      );
+    }
+
+    const data = await withSpinner(
+      'Suppressing addresses...',
+      () => resend.suppressions.batch.add({ emails }),
+      'create_error',
+      globalOpts,
+    );
+
+    if (!globalOpts.json && isInteractive()) {
+      console.log(
+        `Suppressed ${data.data.length} address${data.data.length === 1 ? '' : 'es'}`,
+      );
+      for (const entry of data.data) {
+        console.log(`  ${entry.id}`);
+      }
+    } else {
+      outputResult(data, { json: globalOpts.json });
+    }
+  });

src/commands/suppressions/batch/add.ts

@@ -0,0 +1,21 @@
+import { Command } from '@commander-js/extra-typings';
+import { buildHelpText } from '../../../lib/help-text';
+import { batchAddSuppressionsCommand } from './add';
+import { batchRemoveSuppressionsCommand } from './remove';
+
+export const batchSuppressionsCommand = new Command('batch')
+  .description('Suppress or remove many addresses in a single request')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `Batch operations read a JSON array of strings from --file (up to 100 per request).
+"add" always operates on emails. "remove" defaults to emails; pass --ids to remove by ID.`,
+      examples: [
+        'resend suppressions batch add --file ./emails.json',
+        'resend suppressions batch remove --file ./emails.json',
+        'resend suppressions batch remove --file ./ids.json --ids',
+      ],
+    }),
+  )
+  .addCommand(batchAddSuppressionsCommand)
+  .addCommand(batchRemoveSuppressionsCommand);