npm - resend-cli - Versions diffs - 1.4.1 → 1.5.0 - Mend

resend-cli 1.4.1 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/README.md +1 -1
package/dist/cli.cjs +280 -227
package/package.json +23 -27
package/skills/resend-cli/SKILL.md +141 -0
package/skills/resend-cli/references/api-keys.md +33 -0
package/skills/resend-cli/references/auth.md +67 -0
package/skills/resend-cli/references/broadcasts.md +81 -0
package/skills/resend-cli/references/contact-properties.md +56 -0
package/skills/resend-cli/references/contacts.md +100 -0
package/skills/resend-cli/references/domains.md +79 -0
package/skills/resend-cli/references/emails.md +177 -0
package/skills/resend-cli/references/error-codes.md +54 -0
package/skills/resend-cli/references/segments.md +39 -0
package/skills/resend-cli/references/templates.md +67 -0
package/skills/resend-cli/references/topics.md +50 -0
package/skills/resend-cli/references/webhooks.md +79 -0
package/skills/resend-cli/references/workflows.md +329 -0

package/skills/resend-cli/references/emails.md ADDED Viewed

@@ -0,0 +1,177 @@
+# emails
+Detailed flag specifications for `resend emails` commands.
+---
+## emails send
+Send an email via the Resend API.
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--from <address>` | string | Yes | Sender address (must be on a verified domain) |
+| `--to <addresses...>` | string[] | Yes | Recipient(s), space-separated |
+| `--subject <subject>` | string | Yes | Email subject line |
+| `--text <text>` | string | One of text/html/html-file | Plain-text body |
+| `--html <html>` | string | One of text/html/html-file | HTML body |
+| `--html-file <path>` | string | One of text/html/html-file | Path to HTML file |
+| `--cc <addresses...>` | string[] | No | CC recipients |
+| `--bcc <addresses...>` | string[] | No | BCC recipients |
+| `--reply-to <address>` | string | No | Reply-to address |
+| `--scheduled-at <datetime>` | string | No | Schedule for later (ISO 8601) |
+| `--attachment <paths...>` | string[] | No | File paths to attach |
+| `--headers <key=value...>` | string[] | No | Custom headers |
+| `--tags <name=value...>` | string[] | No | Email tags |
+| `--idempotency-key <key>` | string | No | Deduplicate request |
+**Output:** `{"id":"<uuid>"}`
+---
+## emails get
+Retrieve a sent email by ID.
+**Argument:** `<id>` — Email UUID
+**Output:**
+```json
+{
+  "object": "email",
+  "id": "<uuid>",
+  "from": "you@domain.com",
+  "to": ["user@example.com"],
+  "subject": "Hello",
+  "last_event": "delivered",
+  "created_at": "<iso-date>",
+  "scheduled_at": null
+}
+```
+---
+## emails list
+List sent emails.
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--limit <n>` | number | 10 | Max results (1-100) |
+| `--after <cursor>` | string | — | Forward pagination cursor |
+| `--before <cursor>` | string | — | Backward pagination cursor |
+**Output:** `{"object":"list","data":[...],"has_more":bool}`
+---
+## emails batch
+Send up to 100 emails in a single request.
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--file <path>` | string | Yes (non-interactive) | Path to JSON file with email array |
+| `--idempotency-key <key>` | string | No | Deduplicate batch |
+| `--batch-validation <mode>` | string | No | `strict` (fail all) or `permissive` (partial success) |
+**JSON file format:**
+```json
+[
+  {"from":"a@domain.com","to":["b@example.com"],"subject":"Hi","text":"Body"},
+  {"from":"a@domain.com","to":["c@example.com"],"subject":"Hi","html":"<b>Body</b>"}
+]
+```
+**Output (success):** `[{"id":"..."},{"id":"..."}]`
+**Output (permissive with errors):** `{"data":[{"id":"..."}],"errors":[{"index":1,"message":"..."}]}`
+**Constraints:** Max 100 emails. Attachments and `scheduled_at` not supported per-email.
+---
+## emails cancel
+Cancel a scheduled email.
+**Argument:** `<id>` — Email UUID
+**Output:** `{"object":"email","id":"..."}`
+---
+## emails update
+Update a scheduled email.
+**Argument:** `<id>` — Email UUID
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--scheduled-at <datetime>` | string | Yes | New schedule (ISO 8601) |
+**Output:** `{"object":"email","id":"..."}`
+---
+## emails receiving list
+List received (inbound) emails. Requires domain receiving enabled.
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--limit <n>` | number | 10 | Max results (1-100) |
+| `--after <cursor>` | string | — | Forward pagination |
+| `--before <cursor>` | string | — | Backward pagination |
+---
+## emails receiving get
+**Argument:** `<id>` — Received email UUID
+Returns full email with html, text, headers, `raw.download_url`, and `attachments[]`.
+---
+## emails receiving attachments
+**Argument:** `<emailId>` — Received email UUID
+Lists attachments with `id`, `filename`, `size`, `content_type`, `download_url`, `expires_at`.
+---
+## emails receiving attachment
+**Arguments:** `<emailId>` `<attachmentId>`
+Returns single attachment object with `download_url`.
+---
+## emails receiving forward
+**Argument:** `<id>` — Received email UUID
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--to <addresses...>` | string[] | Yes | Forward recipients |
+| `--from <address>` | string | Yes | Sender address |
+**Output:** `{"id":"..."}`
+---
+## emails receiving listen
+Poll for new inbound emails and display them as they arrive. Long-running command; Ctrl+C exits cleanly.
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--interval <seconds>` | number | 5 | Polling interval in seconds (minimum 2) |
+**Behavior:**
+- Interactive: one-line-per-email display (timestamp, from, to, subject, id)
+- Piped / `--json`: NDJSON (one JSON object per line)
+- Exits after 5 consecutive API failures

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

@@ -0,0 +1,54 @@
+# Error Codes
+All errors exit with code `1` and output JSON to **stderr**:
+```json
+{"error":{"message":"Human-readable description","code":"error_code"}}
+```
+## Authentication Errors
+| Code | Cause | Resolution |
+|------|-------|------------|
+| `auth_error` | No API key found from any source | Set `RESEND_API_KEY` env, pass `--api-key`, or run `resend login --key re_xxx` |
+| `missing_key` | `login` called non-interactively without `--key` | Pass `--key re_xxx` |
+| `invalid_key_format` | API key does not start with `re_` | Use a valid Resend API key starting with `re_` |
+| `validation_failed` | Resend API rejected the key during login | Verify the key exists and is active at resend.com/api-keys |
+## Email Errors
+| Code | Cause | Resolution |
+|------|-------|------------|
+| `missing_body` | None of `--text`, `--html`, or `--html-file` provided | Provide at least one body flag |
+| `file_read_error` | Could not read file from `--html-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 |
+## Domain Errors
+| Code | Cause | Resolution |
+|------|-------|------------|
+| `domain_error` | Domain creation, verification, or update failed | Check domain name is valid; check DNS records are configured |
+## General Errors
+| Code | Cause | Resolution |
+|------|-------|------------|
+| `unexpected_error` | Unhandled exception | Check CLI version with `resend update`; report at github.com/resend/resend-cli/issues |
+| `unknown` | Error without a specific code | Inspect the `message` field for details |
+## Troubleshooting
+### "No API key found" in CI
+Ensure `RESEND_API_KEY` is set in the environment. The CLI does not prompt in non-TTY mode.
+### "Missing required flags" errors
+In non-interactive mode (CI, piped, agent), ALL required flags must be provided. The CLI will not prompt.
+### Deletion commands fail without `--yes`
+All `delete`/`rm` subcommands require `--yes` in non-interactive mode to prevent accidental deletion.
+### API rate limits
+The Resend API has rate limits. If you hit them, the error message will indicate rate limiting. Add delays between batch operations.
+### Scheduled email errors
+`--scheduled-at` must be a valid ISO 8601 datetime. The scheduled time must be in the future.

package/skills/resend-cli/references/segments.md ADDED Viewed

@@ -0,0 +1,39 @@
+# segments
+Detailed flag specifications for `resend segments` commands.
+---
+## segments list
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--limit <n>` | number | 10 | Max results (1-100) |
+| `--after <cursor>` | string | — | Forward pagination |
+| `--before <cursor>` | string | — | Backward pagination |
+---
+## segments create
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--name <name>` | string | Yes (non-interactive) | Segment name |
+---
+## segments get
+**Argument:** `<id>` — Segment UUID
+---
+## segments delete
+**Argument:** `<id>` — Segment UUID
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--yes` | boolean | Yes (non-interactive) | Skip confirmation |
+Deleting a segment does NOT delete its contacts.

package/skills/resend-cli/references/templates.md ADDED Viewed

@@ -0,0 +1,67 @@
+# templates
+Detailed flag specifications for `resend templates` commands.
+---
+## templates list
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--limit <n>` | number | 10 | Max results (1-100) |
+| `--after <cursor>` | string | — | Forward pagination |
+| `--before <cursor>` | string | — | Backward pagination |
+---
+## templates create
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--name <name>` | string | Yes | Template name |
+| `--html <html>` | string | One of html/html-file | HTML body with `{{{VAR_NAME}}}` placeholders |
+| `--html-file <path>` | string | One of html/html-file | Path to HTML file |
+| `--subject <subject>` | string | No | Email subject |
+| `--text <text>` | string | No | Plain-text body |
+| `--from <address>` | string | No | Sender address |
+| `--reply-to <address>` | string | No | Reply-to address |
+| `--alias <alias>` | string | No | Lookup alias |
+| `--var <var...>` | string[] | No | Variables: `KEY:type` or `KEY:type:fallback` |
+Variable types: `string`, `number`
+---
+## templates get
+**Argument:** `<id|alias>` — Template ID or alias
+---
+## templates update
+**Argument:** `<id|alias>` — Template ID or alias
+Same optional flags as `create`. At least one required.
+---
+## templates publish
+**Argument:** `<id|alias>` — Promotes draft to published.
+---
+## templates duplicate
+**Argument:** `<id|alias>` — Creates a copy as draft.
+---
+## templates delete
+**Argument:** `<id|alias>`
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--yes` | boolean | Yes (non-interactive) | Skip confirmation |

package/skills/resend-cli/references/topics.md ADDED Viewed

@@ -0,0 +1,50 @@
+# topics
+Detailed flag specifications for `resend topics` commands.
+---
+## topics list
+Lists all topics. No pagination flags.
+---
+## topics create
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--name <name>` | string | Yes (non-interactive) | Topic name |
+| `--description <desc>` | string | No | Description |
+| `--default-subscription <mode>` | string | No | `opt_in` (default) \| `opt_out` |
+---
+## topics get
+**Argument:** `<id>` — Topic UUID
+---
+## topics update
+**Argument:** `<id>` — Topic UUID
+| Flag | Type | Description |
+|------|------|-------------|
+| `--name <name>` | string | New name |
+| `--description <desc>` | string | New description |
+At least one of `--name` or `--description` is required — otherwise the CLI errors with `no_changes`.
+`default_subscription` cannot be changed after creation.
+---
+## topics delete
+**Argument:** `<id>` — Topic UUID
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--yes` | boolean | Yes (non-interactive) | Skip confirmation |

package/skills/resend-cli/references/webhooks.md ADDED Viewed

@@ -0,0 +1,79 @@
+# webhooks
+Detailed flag specifications for `resend webhooks` commands.
+---
+## webhooks list
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--limit <n>` | number | 10 | Max results (1-100) |
+| `--after <cursor>` | string | — | Forward pagination |
+| `--before <cursor>` | string | — | Backward pagination |
+---
+## webhooks create
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--endpoint <url>` | string | Yes (non-interactive) | HTTPS webhook URL |
+| `--events <events...>` | string[] | Yes (non-interactive) | Event types or `all` |
+**All 17 events:**
+- Email: `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`, `email.failed`, `email.scheduled`, `email.suppressed`, `email.received`
+- Contact: `contact.created`, `contact.updated`, `contact.deleted`
+- Domain: `domain.created`, `domain.updated`, `domain.deleted`
+**Output includes `signing_secret`** — shown once only. Save immediately.
+---
+## webhooks get
+**Argument:** `<id>` — Webhook ID
+**Note:** `signing_secret` is NOT returned by get (only at creation).
+---
+## webhooks update
+**Argument:** `<id>` — Webhook ID
+| Flag | Type | Description |
+|------|------|-------------|
+| `--endpoint <url>` | string | New HTTPS URL |
+| `--events <events...>` | string[] | Replace event list (not additive) |
+| `--status <status>` | string | `enabled` \| `disabled` |
+---
+## webhooks delete
+**Argument:** `<id>` — Webhook ID
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--yes` | boolean | Yes (non-interactive) | Skip confirmation |
+---
+## webhooks listen
+Start a local server that receives Resend webhook events in real time via a public tunnel URL.
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--url <url>` | string | — | Public tunnel URL for receiving webhooks (required in non-interactive) |
+| `--forward-to <url>` | string | — | Forward payloads to this local URL (preserves Svix headers) |
+| `--events <events...>` | string[] | all | Event types to listen for |
+| `--port <port>` | number | 4318 | Local server port |
+**Behavior:**
+1. Starts a local HTTP server on `--port`
+2. Registers a temporary Resend webhook pointing at `--url`
+3. Displays incoming events in the terminal
+4. Optionally forwards payloads to `--forward-to` with original Svix headers
+5. Deletes the temporary webhook on exit (Ctrl+C)