resend-cli 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resend-cli",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "The official CLI for Resend",
   "license": "MIT",
   "repository": {
@@ -18,7 +18,7 @@
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@11.2.2",
+  "packageManager": "pnpm@11.8.0",
   "files": [
     "dist/cli.cjs",
     "skills/"
@@ -43,7 +43,7 @@
     "@clack/prompts": "1.4.0",
     "@commander-js/extra-typings": "14.0.0",
     "commander": "14.0.3",
-    "esbuild": "0.28.0",
+    "esbuild": "0.28.1",
     "esbuild-wasm": "0.28.0",
     "picocolors": "1.1.1",
     "resend": "6.14.0"
@@ -61,9 +61,9 @@
   "devDependencies": {
     "@biomejs/biome": "2.4.11",
     "@types/node": "24.12.4",
-    "@yao-pkg/pkg": "6.19.0",
-    "tsx": "4.22.3",
+    "@yao-pkg/pkg": "6.20.0",
+    "tsx": "4.22.4",
     "typescript": "5.9.3",
-    "vitest": "4.1.7"
+    "vitest": "4.1.9"
   }
 }

package/skills/resend-cli/SKILL.md

@@ -11,6 +11,8 @@ description: >
 license: MIT
 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.0"
   homepage: https://resend.com/docs/cli-agents
   source: https://github.com/resend/resend-cli
@@ -145,7 +147,7 @@ Auth resolves: `--api-key` flag > `RESEND_API_KEY` env > config file (`resend lo
 | `automations` | create, get, list, update, delete, stop, open, runs |
 | `events` | create, get, list, update, delete, send, open |
 | `broadcasts` | create, send, update, delete, list |
-| `contacts` | create, update, delete, segments, topics |
+| `contacts` | create, update, delete, segments, topics, imports |
 | `contact-properties` | create, update, delete, list |
 | `segments` | create, get, list, delete, contacts |
 | `templates` | create, publish, duplicate, delete, list |
@@ -170,6 +172,7 @@ Read the matching reference file for detailed flags and output shapes.
 | 6 | **Sending a dashboard-created broadcast via CLI** | Only API-created broadcasts can be sent with `broadcasts send` — dashboard broadcasts must be sent from the dashboard |
 | 7 | **Passing `--events` to `webhooks update` expecting additive behavior** | `--events` replaces the entire subscription list — always pass the complete set |
 | 8 | **Expecting `logs list` to include request/response bodies** | List returns summary fields only — use `logs get <id>` for full `request_body` and `response_body` |
+| 9 | **CSV import fails with `create_error` ("missing required email column")** | `contacts imports create` matches columns case-sensitively by lowercase names (`email`, `first_name`, `last_name`) — use `--column-map` for headers like `Email`/`First Name` |
 
 ## Common Patterns
 

package/skills/resend-cli/references/contacts.md

@@ -98,3 +98,44 @@ List contact's topic subscriptions.
 | `--topics <json>` | string | Yes (non-interactive) | JSON array: `[{"id":"topic-uuid","subscription":"opt_in"}]` |
 
 Subscription values: `opt_in` | `opt_out`
+
+---
+
+## contacts imports create
+
+Bulk-import contacts from a local CSV file. The file is uploaded as multipart form data (max 100MB). Imports run **asynchronously** — the command returns an import id immediately while the file is processed in the background (poll with `contacts imports get`).
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--file <path>` | string | Yes (non-interactive) | Path to the CSV file to import |
+| `--column-map <json>` | string | No | JSON object mapping contact fields to CSV column headers: `{"email":"Email","firstName":"First Name","properties":{"plan":{"column":"Plan","type":"string"}}}` |
+| `--on-conflict <strategy>` | string | No | How to handle existing contacts: `upsert` (default, updates) or `skip` |
+| `--segment-id <id...>` | string[] | No | Add imported contacts to segment(s) — repeatable |
+| `--topics <json>` | string | No | JSON array: `[{"id":"topic-uuid","subscription":"opt_in"}]` |
+
+Mappable contact fields: `email`, `firstName`, `lastName`, `unsubscribed`, `properties`.
+
+Without `--column-map`, columns are matched by the lowercase names `email` (required), `first_name`, `last_name` — matching is **case-sensitive**, so a CSV with `Email`/`First Name` headers fails with `create_error` (422 "missing required email column"). Use `--column-map` to import such a file.
+
+---
+
+## contacts imports get
+
+Retrieve a contact import's status and counts.
+
+**Argument:** `[id]` — Contact import ID (interactive picker when omitted)
+
+Status values: `queued` | `in_progress` | `completed` | `failed`
+
+---
+
+## contacts imports list
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--limit <n>` | number | 10 | Max results (1-100) |
+| `--after <cursor>` | string | — | Forward pagination |
+| `--before <cursor>` | string | — | Backward pagination |
+| `--status <status>` | string | — | Filter by status: `queued` \| `in_progress` \| `completed` \| `failed` |
+
+**Alias:** `ls`

package/skills/resend-cli/references/error-codes.md

@@ -22,9 +22,18 @@ All errors exit with code `1` and output JSON to **stderr**:
 | `missing_body` | None of `--text`, `--html`, `--html-file`, or `--react-email` provided | Provide at least one body flag |
 | `react_email_build_error` | Failed to bundle a React Email `.tsx` template with esbuild | Check the template compiles; ensure `react` and one of `react-email` (6.0+), `@react-email/components` (5.x), or `@react-email/render` are installed in the project |
 | `react_email_render_error` | Bundled template failed during `render()` | Check the component exports a default function and renders valid React Email markup |
-| `file_read_error` | Could not read file from `--html-file` path | Check file path exists and is readable |
+| `file_read_error` | Could not read file from a `--file`/`--html-file`/`--text-file` path | Check file path exists and is readable |
 | `send_error` | Resend API rejected the send request | Check from address is on a verified domain; check recipient is valid |
 
+## Contact Import Errors
+
+| Code | Cause | Resolution |
+|------|-------|------------|
+| `missing_file` | `contacts imports create` called non-interactively without `--file` | Pass `--file <path>` to the CSV to import |
+| `invalid_column_map` | `--column-map` is not valid JSON, or is not an object | Pass a JSON object mapping contact fields to CSV headers, e.g. `{"email":"Email"}` |
+| `invalid_topics` | `--topics` is not valid JSON, or is not an array | Pass a JSON array of `{id, subscription}` objects |
+| `create_error` | Resend API rejected the import (e.g. CSV missing the required `email` column, or file over 100MB) | Ensure the CSV has an `email` column (or map it with `--column-map`) and is under 100MB |
+
 ## Domain Errors
 
 | Code | Cause | Resolution |

package/skills/resend-cli/references/workflows.md

@@ -414,3 +414,40 @@ resend emails receiving listen --interval 10
 # Stream as NDJSON (for scripting)
 resend emails receiving listen --json | head -3
 ```
+
+---
+
+## 13. Bulk Import Contacts from CSV
+
+```bash
+# 1. Prepare a CSV. Without --column-map, columns are matched by the lowercase
+#    names email (required), first_name, last_name — matching is CASE-SENSITIVE,
+#    so headers like "Email" or "First Name" will NOT match (import fails with a
+#    422 "missing required email column"). Map those with --column-map instead.
+cat > contacts.csv << 'EOF'
+email,first_name,last_name
+ada@example.com,Ada,Lovelace
+alan@example.com,Alan,Turing
+EOF
+
+# 2. Start the import (returns an import id immediately; runs async)
+resend contacts imports create --file ./contacts.csv
+
+# If your CSV uses different header names, map them with --column-map.
+# You can also set a conflict strategy and add contacts to a segment:
+cat > contacts-custom.csv << 'EOF'
+Email,First Name,Last Name
+ada@example.com,Ada,Lovelace
+EOF
+resend contacts imports create \
+  --file ./contacts-custom.csv \
+  --column-map '{"email":"Email","firstName":"First Name","lastName":"Last Name"}' \
+  --on-conflict upsert \
+  --segment-id <segment-id>
+
+# 3. Poll status until "completed" (or "failed")
+resend contacts imports get <import-id>
+
+# 4. Review past imports (filter by status)
+resend contacts imports list --status completed
+```