Resend CLI
This skill is for agents that should operate Resend through the official CLI first, not by
dropping straight to raw REST.
The goal is not just “know the commands”. The goal is to make an agent:
- choose the right Resend primitive,
- choose the right CLI command,
- run it in a deterministic non-interactive way,
- detect the important CLI coverage gaps before it gets stuck, and
- fall back to MCP/API only when the CLI genuinely does not cover the job.
Start here
Load only the files that match the task:
references/agent-operating-model.md — the default decision process for live Resend work
references/install-auth-and-profiles.md — install methods, auth priority, profiles, config paths
references/subprocess-contract.md — how agents should invoke resend safely and parse output
references/command-selection.md — fast routing from user intent to the right command(s)
references/sending-scheduling-and-batch.md — transactional sends, schedules, tags, attachments, batch limits
references/domains-dns-and-deliverability.md — domain creation, verification, receiving, TLS, tracking, 403/domain mismatch
references/webhooks-and-listeners.md — webhook creation, update, signature handling, temporary local listeners
references/inbound-receiving-and-threading.md — inbound list/get/attachments/forward/listen flows
references/contacts-topics-segments-and-broadcasts.md — subscription modelling, targeting, campaigns
references/templates-and-coverage-gaps.md — template lifecycle and the important current CLI gaps
references/diagnostics-and-fallbacks.md — debug order, CLI quirks, when to fall back to MCP/API
references/recipes.md — short end-to-end playbooks
references/sources.md — first-party source manifest and refresh notes
Machine-readable assets:
assets/command-catalog.json — command index with detail levels (source_inspected, readme_confirmed, tree_confirmed)
assets/task-router.json — route common tasks to command sequences
assets/error-map.json — fast-fail diagnosis hints
assets/coverage-gaps.json — current CLI limitations and ambiguities that matter to agents
assets/subprocess-contract.json — deterministic invocation defaults
assets/scaffold-index.json — reusable command/file scaffolds
assets/source-manifest.json — authoritative URLs used to build this skill
Bundled helper:
scripts/resend_cli.py — agent wrapper for probing, routing, scaffolding, batch linting, diagnosis, and safe subprocess execution
Core operating rules
1) Prefer the official CLI for live Resend work
Default order of preference:
- Official Resend CLI for live terminal/CI/agent operations
- Official Resend MCP server if the environment already exposes it and the CLI is unavailable
- Official SDK when editing app code inside an existing integration
- Raw REST only for stack-neutral examples, protocol debugging, or feature gaps
Do not choose raw REST just because it is familiar.
2) For agents, stay non-interactive by default
For bounded commands:
- pass all required flags explicitly
- use global
--json -q
- prefer
RESEND_API_KEY or a stored profile over typing secrets interactively
- set
RESEND_NO_UPDATE_NOTIFIER=1 for deterministic output
- capture both stdout and stderr defensively
3) Run doctor early when the environment is unknown
When you do not know whether the CLI is installed, authenticated, or pointed at the right account:
resend --json -q doctor
This is usually the fastest first read on:
- CLI availability/version
- whether an API key is being resolved
- whether verified domains exist
- whether the machine looks like an AI-agent environment
4) Choose the primitive before the command
- One logical transactional email →
emails send
- Up to 100 distinct transactional emails in one request →
emails batch
- Scheduled transactional email mutation →
emails update / emails cancel
- Campaign to a segment →
broadcasts create / broadcasts send
- Reusable hosted content →
templates *
- Sender or receiving setup →
domains *
- Inbound processing →
emails receiving * + webhooks *
- Scoped credentials →
api-keys *
- Recipient data and preferences →
contacts, contact-properties, topics, segments
- Local dev event loop →
webhooks listen or emails receiving listen
5) Know the current CLI gaps
This version of the skill treats these as especially important:
- Template send gap: the CLI manages templates, but the current
emails send command surface does not expose a direct --template-id/template-vars flow.
- Domain capability update gap:
domains update exposes TLS/open/click tracking, but not an explicit sending/receiving capability toggle, while inbound help text references such a toggle.
- Stream commands are special:
webhooks listen and emails receiving listen are long-running and should be treated as NDJSON/event streams in agent mode.
- JSON error channel discrepancy: the README promises machine JSON on stdout only, but the current source writes JSON errors with
console.error, so wrappers must parse stderr too.
6) Keep IDs and file paths
Most multi-step flows become much easier if the agent persists:
- domain IDs
- email IDs
- webhook IDs
- topic IDs
- segment IDs
- template IDs/aliases
- API key IDs
- the file paths it generated for HTML or batch JSON
The mutation ladder
For state-changing live operations:
- classify the task
- confirm the command sequence
- make any needed file assets (
.html, batch JSON)
- run with
--json -q
- verify with
get, list, or a follow-up check
- persist returned IDs and next-step context
- only then continue to the next mutation
Bundled helper script
scripts/resend_cli.py is intentionally agent-oriented.
Commands:
probe — find the CLI, report install hints, and show environment basics
catalog — list known commands from the bundled catalogue
info — inspect one command and its notes/gaps
recommend — route a free-text task to the best CLI sequence
scaffold — print or materialise sample commands/files
lint-batch — statically validate an emails batch JSON file
doctor — explain likely causes of common CLI/API failures
run — execute the official CLI with deterministic defaults and tolerant JSON parsing
Examples:
python3 scripts/resend_cli.py probe
python3 scripts/resend_cli.py catalog --resource emails
python3 scripts/resend_cli.py info "emails send"
python3 scripts/resend_cli.py recommend "send 70 different shipment notifications"
python3 scripts/resend_cli.py scaffold batch-send --write-dir ./tmp
python3 scripts/resend_cli.py lint-batch ./tmp/batch-emails.json
python3 scripts/resend_cli.py doctor --command "emails send" --status 403 --message "1010 forbidden"
python3 scripts/resend_cli.py run -- emails list --limit 5
Response shape this skill should produce
A strong answer usually includes:
- the exact Resend primitive,
- the exact CLI command or command sequence,
- any file scaffolding the user needs,
- the operational caveats that matter here,
- the verification step,
- the fallback path if the CLI does not currently cover the flow.
Example prompts this skill should handle
- “Use the Resend CLI to send a scheduled password reset email”
- “Should I use
emails send, emails batch, or broadcasts create?”
- “Create a sending + receiving domain in
eu-west-1”
- “Set up local webhook listening with ngrok”
- “Why is my batch file failing?”
- “How do I manage multiple Resend accounts from one agent?”
- “Can the CLI send a hosted template directly?”
- “How should my agent parse
resend output safely?”
1---
2name: resend-cli
3description: "Use this skill when the task is specifically about operating Resend from an AI agent, terminal session, or CI job via the official resend CLI: installing/authenticating the CLI, sending/listing/updating/cancelling emails, batch sends, domains and DNS, webhooks and local listeners, inbound receiving, contacts, topics, segments, broadcasts, templates, API keys, profiles, or debugging Resend CLI/API failures. Trigger on mentions of Resend CLI, `resend`, `resend doctor`, `resend emails send`, `resend domains`, `resend webhooks listen`, `resend emails receiving`, or agent-friendly terminal automation."
4compatibility: "Designed for skills-compatible coding agents. Live operations require the official `resend` CLI plus a `RESEND_API_KEY` or stored profile. The bundled helper uses Python 3.10+ standard library only."
5metadata:
6 author: OpenAI
7 version: "3.0.0"
8 cli-version: "1.4.1"
9 source: https://skillmd.com/skills/tristanmanchester/resend-cli
10 upstream: "https://github.com/resend/resend-cli"
11 last-reviewed: "2026-03-14"
12---
13
14# Resend CLI
15
16This skill is for agents that should operate **Resend through the official CLI first**, not by
17dropping straight to raw REST.
18
19The goal is not just “know the commands”. The goal is to make an agent:
20
211. choose the right Resend primitive,
222. choose the right CLI command,
233. run it in a deterministic non-interactive way,
244. detect the important CLI coverage gaps before it gets stuck, and
255. fall back to MCP/API only when the CLI genuinely does not cover the job.
26
27## Start here
28
29Load only the files that match the task:
30
31- `references/agent-operating-model.md` — the default decision process for live Resend work
32- `references/install-auth-and-profiles.md` — install methods, auth priority, profiles, config paths
33- `references/subprocess-contract.md` — how agents should invoke `resend` safely and parse output
34- `references/command-selection.md` — fast routing from user intent to the right command(s)
35- `references/sending-scheduling-and-batch.md` — transactional sends, schedules, tags, attachments, batch limits
36- `references/domains-dns-and-deliverability.md` — domain creation, verification, receiving, TLS, tracking, 403/domain mismatch
37- `references/webhooks-and-listeners.md` — webhook creation, update, signature handling, temporary local listeners
38- `references/inbound-receiving-and-threading.md` — inbound list/get/attachments/forward/listen flows
39- `references/contacts-topics-segments-and-broadcasts.md` — subscription modelling, targeting, campaigns
40- `references/templates-and-coverage-gaps.md` — template lifecycle and the important current CLI gaps
41- `references/diagnostics-and-fallbacks.md` — debug order, CLI quirks, when to fall back to MCP/API
42- `references/recipes.md` — short end-to-end playbooks
43- `references/sources.md` — first-party source manifest and refresh notes
44
45Machine-readable assets:
46
47- `assets/command-catalog.json` — command index with detail levels (`source_inspected`, `readme_confirmed`, `tree_confirmed`)
48- `assets/task-router.json` — route common tasks to command sequences
49- `assets/error-map.json` — fast-fail diagnosis hints
50- `assets/coverage-gaps.json` — current CLI limitations and ambiguities that matter to agents
51- `assets/subprocess-contract.json` — deterministic invocation defaults
52- `assets/scaffold-index.json` — reusable command/file scaffolds
53- `assets/source-manifest.json` — authoritative URLs used to build this skill
54
55Bundled helper:
56
57- `scripts/resend_cli.py` — agent wrapper for probing, routing, scaffolding, batch linting, diagnosis, and safe subprocess execution
58
59## Core operating rules
60
61### 1) Prefer the official CLI for live Resend work
62
63Default order of preference:
64
651. **Official Resend CLI** for live terminal/CI/agent operations
662. **Official Resend MCP server** if the environment already exposes it and the CLI is unavailable
673. **Official SDK** when editing app code inside an existing integration
684. **Raw REST** only for stack-neutral examples, protocol debugging, or feature gaps
69
70Do not choose raw REST just because it is familiar.
71
72### 2) For agents, stay non-interactive by default
73
74For bounded commands:
75
76- pass all required flags explicitly
77- use global `--json -q`
78- prefer `RESEND_API_KEY` or a stored profile over typing secrets interactively
79- set `RESEND_NO_UPDATE_NOTIFIER=1` for deterministic output
80- capture **both stdout and stderr** defensively
81
82### 3) Run `doctor` early when the environment is unknown
83
84When you do not know whether the CLI is installed, authenticated, or pointed at the right account:
85
86```bash
87resend --json -q doctor
88```
89
90This is usually the fastest first read on:
91
92- CLI availability/version
93- whether an API key is being resolved
94- whether verified domains exist
95- whether the machine looks like an AI-agent environment
96
97### 4) Choose the primitive before the command
98
99- One logical transactional email → `emails send`
100- Up to 100 distinct transactional emails in one request → `emails batch`
101- Scheduled transactional email mutation → `emails update` / `emails cancel`
102- Campaign to a segment → `broadcasts create` / `broadcasts send`
103- Reusable hosted content → `templates *`
104- Sender or receiving setup → `domains *`
105- Inbound processing → `emails receiving *` + `webhooks *`
106- Scoped credentials → `api-keys *`
107- Recipient data and preferences → `contacts`, `contact-properties`, `topics`, `segments`
108- Local dev event loop → `webhooks listen` or `emails receiving listen`
109
110### 5) Know the current CLI gaps
111
112This version of the skill treats these as especially important:
113
114- **Template send gap:** the CLI manages templates, but the current `emails send` command surface does not expose a direct `--template-id`/template-vars flow.
115- **Domain capability update gap:** `domains update` exposes TLS/open/click tracking, but not an explicit sending/receiving capability toggle, while inbound help text references such a toggle.
116- **Stream commands are special:** `webhooks listen` and `emails receiving listen` are long-running and should be treated as NDJSON/event streams in agent mode.
117- **JSON error channel discrepancy:** the README promises machine JSON on stdout only, but the current source writes JSON errors with `console.error`, so wrappers must parse stderr too.
118
119### 6) Keep IDs and file paths
120
121Most multi-step flows become much easier if the agent persists:
122
123- domain IDs
124- email IDs
125- webhook IDs
126- topic IDs
127- segment IDs
128- template IDs/aliases
129- API key IDs
130- the file paths it generated for HTML or batch JSON
131
132## The mutation ladder
133
134For state-changing live operations:
135
1361. classify the task
1372. confirm the command sequence
1383. make any needed file assets (`.html`, batch JSON)
1394. run with `--json -q`
1405. verify with `get`, `list`, or a follow-up check
1416. persist returned IDs and next-step context
1427. only then continue to the next mutation
143
144## Bundled helper script
145
146`scripts/resend_cli.py` is intentionally agent-oriented.
147
148Commands:
149
150- `probe` — find the CLI, report install hints, and show environment basics
151- `catalog` — list known commands from the bundled catalogue
152- `info` — inspect one command and its notes/gaps
153- `recommend` — route a free-text task to the best CLI sequence
154- `scaffold` — print or materialise sample commands/files
155- `lint-batch` — statically validate an `emails batch` JSON file
156- `doctor` — explain likely causes of common CLI/API failures
157- `run` — execute the official CLI with deterministic defaults and tolerant JSON parsing
158
159Examples:
160
161```bash
162python3 scripts/resend_cli.py probe
163python3 scripts/resend_cli.py catalog --resource emails
164python3 scripts/resend_cli.py info "emails send"
165python3 scripts/resend_cli.py recommend "send 70 different shipment notifications"
166python3 scripts/resend_cli.py scaffold batch-send --write-dir ./tmp
167python3 scripts/resend_cli.py lint-batch ./tmp/batch-emails.json
168python3 scripts/resend_cli.py doctor --command "emails send" --status 403 --message "1010 forbidden"
169python3 scripts/resend_cli.py run -- emails list --limit 5
170```
171
172## Response shape this skill should produce
173
174A strong answer usually includes:
175
1761. the exact Resend primitive,
1772. the exact CLI command or command sequence,
1783. any file scaffolding the user needs,
1794. the operational caveats that matter here,
1805. the verification step,
1816. the fallback path if the CLI does not currently cover the flow.
182
183## Example prompts this skill should handle
184
185- “Use the Resend CLI to send a scheduled password reset email”
186- “Should I use `emails send`, `emails batch`, or `broadcasts create`?”
187- “Create a sending + receiving domain in `eu-west-1`”
188- “Set up local webhook listening with ngrok”
189- “Why is my batch file failing?”
190- “How do I manage multiple Resend accounts from one agent?”
191- “Can the CLI send a hosted template directly?”
192- “How should my agent parse `resend` output safely?”