Skip to content
Back to search

resend-cli

The official CLI for Resend

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/resend/resend-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/resend/resend-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/resend--resend-cli/badge.svg)](/listings/resend--resend-cli)

HTML

<a href="/listings/resend--resend-cli"><img src="/api/listings/resend--resend-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

cURL

curl -fsSL https://resend.com/install.sh | bash

Node.js

npm install -g resend-cli

Homebrew (macOS / Linux)

brew install resend/cli/resend

PowerShell (Windows)

irm https://resend.com/install.ps1 | iex

Or download the `.exe` directly from the [GitHub releases page](https://github.com/resend/resend-cli/releases/latest).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,064 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Resend CLI
  2. The official CLI for [Resend](https://resend.com).
  3. Built for humans, AI agents, and CI/CD pipelines.
  4. ```
  5. ██████╗ ███████╗███████╗███████╗███╗ ██╗██████╗
  6. ██╔══██╗██╔════╝██╔════╝██╔════╝████╗ ██║██╔══██╗
  7. ██████╔╝█████╗ ███████╗█████╗ ██╔██╗ ██║██║ ██║
  8. ██╔══██╗██╔══╝ ╚════██║██╔══╝ ██║╚██╗██║██║ ██║
  9. ██║ ██║███████╗███████║███████╗██║ ╚████║██████╔╝
  10. ╚═╝ ╚═╝╚══════╝╚══════╝╚══════╝╚═╝ ╚═══╝╚═════╝
  11. ```
  12. ## Install
  13. ### cURL
  14. ```sh
  15. curl -fsSL https://resend.com/install.sh | bash
  16. ```
  17. ### Node.js
  18. ```sh
  19. npm install -g resend-cli
  20. ```
  21. ### Homebrew (macOS / Linux)
  22. ```sh
  23. brew install resend/cli/resend
  24. ```
  25. ### PowerShell (Windows)
  26. ```sh
  27. irm https://resend.com/install.ps1 | iex
  28. ```
  29. Or download the `.exe` directly from the [GitHub releases page](https://github.com/resend/resend-cli/releases/latest).
  30. ## Quickstart
  31. ```bash
  32. # Authenticate
  33. resend login
  34. # Send an email
  35. resend emails send \
  36. --from "you@example.com" \
  37. --to delivered@resend.dev \
  38. --subject "Hello from Resend CLI" \
  39. --text "Sent from my terminal."
  40. # Check your environment
  41. resend doctor
  42. ```
  43. ## Agent skills
  44. This CLI ships with an [agent skill](skills/resend-cli/SKILL.md) that teaches AI coding agents (Cursor, Claude Code, Windsurf, etc.) how to use the Resend CLI effectively, including non-interactive flags, output formats, and common pitfalls.
  45. To install skills for Resend's full platform (API, CLI, React Email, email best practices) from the [central skills repository](https://github.com/resend/resend-skills):
  46. ```sh
  47. npx skills add resend/resend-skills
  48. ```
  49. ## Local development
  50. Use this when you want to change the CLI and run your build locally.
  51. ### Prerequisites
  52. - [Node.js](https://nodejs.org) 20+
  53. ### Setup
  54. 1. **Clone the repo**
  55. ```bash
  56. git clone https://github.com/resend/resend-cli.git
  57. cd resend-cli
  58. ```
  59. 2. **Install dependencies**
  60. ```bash
  61. pnpm install
  62. ```
  63. 3. **Build locally**
  64. ```bash
  65. pnpm build
  66. ```
  67. Output: `./dist/cli.cjs`
  68. ## Running the CLI locally
  69. Use the dev script:
  70. ```bash
  71. pnpm dev --version
  72. ```
  73. Or run the built JS bundle:
  74. ```bash
  75. node dist/cli.cjs --version
  76. ```
  77. ### Making changes
  78. After editing source files, rebuild:
  79. ```bash
  80. pnpm build
  81. ```
  82. ### Building native binaries
  83. To build a standalone native binary:
  84. ```bash
  85. pnpm build:bin
  86. ```
  87. Output: `./dist/resend`
  88. ---
  89. ## Authentication
  90. The CLI resolves your API key using the following priority chain:
  91. | Priority | Source | How to set |
  92. | ----------- | ------------------------ | ----------------------------------------- |
  93. | 1 (highest) | `--api-key` flag | `resend --api-key re_xxx emails send ...` |
  94. | 2 | `RESEND_API_KEY` env var | `export RESEND_API_KEY=re_xxx` |
  95. | 3 (lowest) | Config file | `resend login` |
  96. If no key is found from any source, the CLI errors with code `auth_error`.
  97. ---
  98. ## Commands
  99. ### `resend login`
  100. Authenticate by storing your API key locally. The key is validated against the Resend API before being saved.
  101. ```bash
  102. resend login
  103. ```
  104. #### Interactive mode (default in terminals)
  105. When run in a terminal, the command checks for an existing key:
  106. - **No key found**: Offers to open the [Resend API keys dashboard](https://resend.com/api-keys) in your browser so you can create one, then prompts for the key.
  107. - **Existing key found**: Shows the key source (`env`, `config`) and prompts for a new key to replace it.
  108. Enter the key via a masked password input. Your key must start with `re_`.
  109. #### Non-interactive mode (CI, pipes, scripts)
  110. The CLI is non-interactive when stdin or stdout is not a TTY, when `CI` or `GITHUB_ACTIONS` is set, or when `TERM=dumb`. In that mode, pass `--web` or `--key`.
  111. `--web` logs in through the browser with no prompts in any mode, so AI agents can run it. The command tries to open the browser, then prints the authorize URL and the target profile to stderr. It waits up to 5 minutes for you to approve the login, then stores an OAuth grant:
  112. ```bash
  113. resend login --web
  114. ```
  115. - The browser must run on the same machine as the CLI, because Resend redirects to a local callback on `127.0.0.1`.
  116. - Without `--profile`, the login goes to the `default` profile and replaces its saved credentials.
  117. - The status text on stderr comes before any JSON error.
  118. `--key` stores an API key:
  119. ```bash
  120. resend login --key re_xxxxxxxxxxxxx
  121. ```
  122. Omitting both flags in non-interactive mode exits with error code `missing_key`.
  123. #### Options
  124. | Flag | Description |
  125. | ------------- | ------------------------------------------------------------------- |
  126. | `--web` | Log in through the browser with no prompts |
  127. | `--key <key>` | API key to store (required in non-interactive mode, unless `--web`) |
  128. #### Output
  129. On success, credentials are saved to `~/.config/resend/credentials.json` with `0600` permissions (owner read/write only). The config directory is created with `0700` permissions.
  130. With `--json`, or when stdout is not a TTY, the result is JSON on stdout:
  131. ```bash
  132. resend login --key re_xxx --json
  133. # => {"success":true,"config_path":"...","profile":"default","storage":"...","permission":"full_access"}
  134. resend login --web --json
  135. # => {"success":true,"config_path":"...","profile":"default","storage":"...","scope":"full_access"}
  136. ```
  137. #### Error codes
  138. | Code | Cause |
  139. | ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
  140. | `missing_key` | No `--key` or `--web` in non-interactive mode |
  141. | `conflicting_flags` | `--web` and `--key` are both set |
  142. | `invalid_key_format` | Key does not start with `re_` |
  143. | `validation_failed` | Resend API rejected the key |
  144. | `invalid_profile_name` | The `--profile` name is not valid |
  145. | `write_failed` | The credentials could not be saved |
  146. | `oauth_error` | Browser login failed: the local callback did not start, access was denied, it timed out, or the token exchange failed |
  147. | `oauth_state_mismatch` | The browser callback did not match this login request |
  148. #### Switch between teams and accounts
  149. If you work across multiple Resend teams or accounts, the CLI handles that, too.
  150. Switch between profiles without logging in and out:
  151. ```bash
  152. resend auth switch
  153. ```
  154. You can also use the global `--profile` (or `-p`) flag on any command to run it with a specific profile.
  155. ```bash
  156. resend domains list --profile production
  157. ```
  158. ---
  159. ### `resend emails send`
  160. Send an email via the Resend API.
  161. Provide all options via flags for scripting, or let the CLI prompt interactively for missing fields.
  162. ```bash
  163. resend emails send \
  164. --from "Name <sender@example.com>" \
  165. --to delivered@resend.dev \
  166. --subject "Subject line" \
  167. --text "Plain text body"
  168. ```
  169. #### Options
  170. | Flag | Required | Description |
  171. | ---------------------- | -------------------------- | ------------------------------------------------------- |
  172. | `--from <address>` | Yes | Sender email address (must be from a verified domain) |
  173. | `--to <addresses...>` | Yes | One or more recipient email addresses (space-separated) |
  174. | `--subject <subject>` | Yes | Email subject line |
  175. | `--text <text>` | One of text/html/html-file | Plain text body |
  176. | `--html <html>` | One of text/html/html-file | HTML body as a string |
  177. | `--html-file <path>` | One of text/html/html-file | Path to an HTML file to use as body |
  178. | `--cc <addresses...>` | No | CC recipients (space-separated) |
  179. | `--bcc <addresses...>` | No | BCC recipients (space-separated) |
  180. | `--reply-to <address>` | No | Reply-to email address |
  181. #### Interactive mode
  182. When run in a terminal without all required flags, the CLI prompts for missing fields:
  183. ```bash
  184. # prompts for from, to, subject, and body
  185. resend emails send
  186. # prompts only for missing fields
  187. resend emails send --from "you@example.com"
  188. ```
  189. #### Non-interactive mode
  190. When piped or run in CI, all required flags must be provided. Missing flags cause an error listing what's needed:
  191. ```bash
  192. echo "" | resend emails send --from "you@example.com"
  193. # Error: Missing required flags: --to, --subject
  194. ```
  195. A body (`--text`, `--html`, or `--html-file`) is also required — omitting all three exits with code `missing_body`.
  196. #### Examples
  197. **Multiple recipients:**
  198. ```bash
  199. resend emails send \
  200. --from "you@example.com" \
  201. --to delivered@resend.dev bounced@resend.dev \
  202. --subject "Team update" \
  203. --text "Hello everyone"
  204. ```
  205. **HTML from a file:**
  206. ```bash
  207. resend emails send \
  208. --from "you@example.com" \
  209. --to delivered@resend.dev \
  210. --subject "Newsletter" \
  211. --html-file ./newsletter.html
  212. ```
  213. **With CC, BCC, and reply-to:**
  214. ```bash
  215. resend emails send \
  216. --from "you@example.com" \
  217. --to delivered@resend.dev \
  218. --subject "Meeting notes" \
  219. --text "See attached." \
  220. --cc manager@example.com \
  221. --bcc delivered+1@resend.dev \
  222. --reply-to support@example.com
  223. ```
  224. **Overriding the API key for one send:**
  225. ```bash
  226. resend --api-key re_other_key emails send \
  227. --from "you@example.com" \
  228. --to delivered@resend.dev \
  229. --subject "Test" \
  230. --text "Using a different key"
  231. ```
  232. #### Output
  233. Returns the email ID on success:
  234. ```json
  235. { "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794" }
  236. ```
  237. #### Error codes
  238. | Code | Cause |
  239. | ----------------- | ------------------------------------------------ |
  240. | `auth_error` | No API key found or client creation failed |
  241. | `missing_body` | No `--text`, `--html`, or `--html-file` provided |
  242. | `file_read_error` | Could not read the file passed to `--html-file` |
  243. | `send_error` | Resend API returned an error |
  244. ---
  245. ### `resend doctor`
  246. Run environment diagnostics. Verifies your CLI version, API key, domains, and detects AI agent integrations.
  247. ```bash
  248. resend doctor
  249. ```
  250. #### Checks performed
  251. | Check | Pass | Warn | Fail |
  252. | --------------- | --------------------------------------- | ---------------------------------------- | --------------- |
  253. | **CLI Version** | Running latest | Update available or registry unreachable | — |
  254. | **API Key** | Key found (shows masked key and source) | — | No key found |
  255. | **Domains** | Verified domains exist | No domains or all pending verification | API key invalid |
  256. | **AI Agents** | Lists detected agents (or none) | — | — |
  257. The API key is always masked in output (e.g. `re_...xxxx`).
  258. #### Interactive mode
  259. In a terminal, shows animated spinners for each check with colored status icons:
  260. ```
  261. Resend Doctor
  262. ✔ CLI Version: v0.1.0 (latest)
  263. ✔ API Key: re_...xxxx (source: env)
  264. ✔ Domains: 2 verified, 0 pending
  265. ✔ AI Agents: Detected: Cursor, Claude Desktop
  266. ```
  267. #### JSON mode
  268. ```bash
  269. resend doctor --json
  270. ```
  271. ```json
  272. {
  273. "ok": true,
  274. "checks": [
  275. { "name": "CLI Version", "status": "pass", "message": "v0.1.0 (latest)" },
  276. {
  277. "name": "API Key",
  278. "status": "pass",
  279. "message": "re_...xxxx (source: env)"
  280. },
  281. { "name": "Domains", "status": "pass", "message": "2 verified, 0 pending" },
  282. { "name": "AI Agents", "status": "pass", "message": "Detected: Cursor" }
  283. ]
  284. }
  285. ```
  286. Each check has a `status` of `pass`, `warn`, or `fail`. The top-level `ok` is `false` if any check is `fail`.
  287. #### Detected AI agents
  288. | Agent | Detection method |
  289. | -------------- | --------------------------------------- |
  290. | OpenClaw | `~/clawd/skills` directory exists |
  291. | Cursor | `~/.cursor` directory exists |
  292. | Claude Desktop | Platform-specific config file exists |
  293. | VS Code | `.vscode/mcp.json` in current directory |
  294. #### Exit code
  295. Exits `0` when all checks pass or warn. Exits `1` if any check fails.
  296. ---
  297. ### Webhooks
  298. With the Resend CLI, you can manage webhook endpoints so your app receives real-time event notifications.
  299. Payloads are signed with [Svix](https://docs.svix.com/receiving/verifying-payloads/how) headers (`svix-id`, `svix-timestamp`, `svix-signature`). Verify them in your app with the Resend SDK.
  300. For example: `resend.webhooks.verify({ payload, headers, webhookSecret })`
  301. There are many events that you can listen for in your application.
  302. For example, you can:
  303. - Set up a POST endpoint to unsubscribe users when an email bounces or they mark your email as spam.
  304. - Notify yourself when you get a new subscriber using the `contact.created` event.
  305. - Use an `email.received` webhook to set up an inbox for your agent and notify it when a new email is received.
  306. #### Event types
  307. | Category | Events |
  308. | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  309. | Email | `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`, `email.failed`, `email.scheduled`, `email.suppressed`, `email.received` |
  310. | Contact | `contact.created`, `contact.updated`, `contact.deleted`, `contact.topics.updated` |
  311. | Domain | `domain.created`, `domain.updated`, `domain.deleted` |
  312. | Topic | `topic.created`, `topic.updated`, `topic.deleted` |
  313. | Inbox | `inbox.created`, `inbox.updated`, `inbox.deleted`, `inbox.thread.created`, `inbox.email.received`, `inbox.email.sent`, `inbox.thread.folder.updated`, `inbox.thread.assigned`, `inbox.thread.unassigned`, `inbox.thread.labels.updated`, `inbox.draft.created`, `inbox.draft.updated`, `inbox.draft.sent`, `inbox.draft.deleted` |
  314. Use `all` with `--events` to subscribe to every event.
  315. #### Subcommands
  316. - `list`
  317. - `create`
  318. - `get`
  319. - `update`
  320. - `delete`
  321. - `rotate-signing-secret`
  322. - `listen`
  323. - `events` (`list`, `get`, `attempts`, `replay`)
  324. #### Aliases
  325. - `webhooks ls` → `list`
  326. - `webhooks rm` → `delete`
  327. - `webhooks events ls` → `webhooks events list`
  328. ---
  329. #### **`resend webhooks list`**
  330. Lists existing webhooks.
  331. Running `resend webhooks` with no subcommand runs `list`.
  332. | Flag | Description |
  333. | ------------------- | --------------------------------------------------------- |
  334. | `--limit <n>` | Max webhooks to return (`1`–`100`, default `10`) |
  335. | `--after <cursor>` | Return webhooks after this cursor (webhook ID; next page) |
  336. | `--before <cursor>` | Return webhooks before this cursor (previous page) |
  337. Only one of `--after` or `--before` may be used. The API response includes `has_more` when more pages exist.
  338. ```bash
  339. resend webhooks list
  340. resend webhooks list --limit 25
  341. resend webhooks list --after wh_abc123 --json
  342. ```
  343. #### **`resend webhooks create`**
  344. Registers a new endpoint.
  345. The endpoint must use **HTTPS**. Use the **`signing_secret`** in the response to verify incoming payloads. `resend webhooks get` returns it again.
  346. In interactive mode, the CLI can prompt for endpoint and events. In non-interactive mode (pipes, CI, `--json`), **`--endpoint` and `--events` are required.**
  347. | Flag | Description |
  348. | ---------------------- | ------------------------------------------------- |
  349. | `--endpoint <url>` | HTTPS URL that receives webhook POSTs |
  350. | `--events <events...>` | Event names (comma- or space-separated), or `all` |
  351. ```bash
  352. resend webhooks create --endpoint https://app.example.com/hooks/resend --events all
  353. resend webhooks create --endpoint https://app.example.com/hooks/resend --events email.sent email.bounced
  354. resend webhooks create --endpoint https://app.example.com/hooks/resend --events email.sent,email.delivered
  355. ```
  356. #### **`resend webhooks get`**
  357. Fetches one webhook by ID.
  358. Omit the ID in a terminal to pick from a list.
  359. ```bash
  360. resend webhooks get wh_abc123
  361. resend webhooks get wh_abc123 --json
  362. ```
  363. The response includes the signing secret. Use `resend webhooks rotate-signing-secret <id>` to replace it.
  364. #### **`resend webhooks update`**
  365. Updates the webhook:
  366. - endpoint URL
  367. - the full event list
  368. - delivery status
  369. **At least one** of `--endpoint`, `--events`, or `--status` is required.
  370. | Flag | Description |
  371. | ---------------------- | ------------------------ |
  372. | `--endpoint <url>` | New HTTPS URL |
  373. | `--events <events...>` | New event list, or `all` |
  374. | `--status <status>` | `enabled` or `disabled` |
  375. Disabled status pauses delivery without deleting the webhook.
  376. ```bash
  377. resend webhooks update wh_abc123 --status disabled
  378. resend webhooks update wh_abc123 --endpoint https://new-app.example.com/hooks/resend
  379. resend webhooks update wh_abc123 --events email.sent email.bounced
  380. ```
  381. #### **`resend webhooks delete`**
  382. Deletes a webhook and stops deliveries.
  383. In non-interactive mode, **`--yes` is required** to confirm.
  384. ```bash
  385. resend webhooks delete wh_abc123 --yes
  386. ```
  387. To pause delivery temporarily, prefer `resend webhooks update <id> --status disabled`.
  388. #### **`resend webhooks rotate-signing-secret`**
  389. Generates a new signing secret for the webhook and returns it. For 24 hours, payloads are signed with both the new and the previous secret, so either one verifies them. After that, only the new secret does.
  390. Omit the ID in a terminal to pick from a list.
  391. ```bash
  392. resend webhooks rotate-signing-secret wh_abc123
  393. resend webhooks rotate-signing-secret wh_abc123 --json
  394. ```
  395. #### **`resend webhooks listen`**
  396. Built-in local development helper. It:
  397. - Starts a small HTTP server
  398. - Registers a temporary Resend webhook pointing at your public tunnel URL
  399. - Prints events in the terminal
  400. - Prints the temporary webhook's signing secret in the banner, so your `--forward-to` app can verify the Svix headers
  401. - Verifies Svix signatures before it prints or forwards events
  402. - Deletes the webhook on exit
  403. Your tunnel must forward to the same port as `--port`, e.g. `ngrok http 4318`.
  404. Requests with missing or invalid signatures receive HTTP 400.
  405. | Flag | Description |
  406. | ---------------------- | ------------------------------------------------------------ |
  407. | `--url <url>` | Public URL (tunnel) that reaches this machine — **required** |
  408. | `--port <port>` | Local server port (default `4318`) |
  409. | `--events <events...>` | Events to subscribe to (default: all) |
  410. | `--forward-to <url>` | Also POST each payload to this URL (Svix headers preserved) |
  411. ```bash
  412. # Terminal 1: tunnel to the listen port
  413. ngrok http 4318
  414. # Terminal 2: use the HTTPS URL ngrok gives you
  415. resend webhooks listen --url https://xxxx.ngrok-free.app
  416. resend webhooks listen --url https://xxxx.ngrok-free.app --forward-to localhost:3000/api/webhooks/resend
  417. resend webhooks listen --url https://xxxx.ngrok-free.app --port 8080 --events email.sent email.bounced
  418. ```
  419. #### **`resend webhooks events`**
  420. Inspects what Resend already delivered to a webhook. Use it to debug an endpoint that is missing events:
  421. 1. `resend webhooks events list <webhook-id>` — find the event
  422. 2. `resend webhooks events get <webhook-id> <event-id>` — see the payload we sent
  423. 3. `resend webhooks events attempts <webhook-id> <event-id>` — see what your endpoint returned
  424. 4. `resend webhooks events replay <webhook-id> <event-id>` — queue another delivery
  425. Running `resend webhooks events <webhook-id>` with no subcommand runs `list`.
  426. Both list subcommands paginate forward only — there is no `--before`.
  427. | Flag | Description |
  428. | ------------------ | -------------------------------------------------------- |
  429. | `--limit <n>` | Max results to return (`1`–`100`, default `10`) |
  430. | `--after <cursor>` | Return results after this ID (next page) |
  431. `events list` reports each event's `type`, `status` (`pending`, `attempting`, `success`, `failed`), and `created_at`. `events get` adds `next_attempt_at` and the payload that was sent. `events attempts` reports the `http_status_code` and response body your endpoint returned for each try. `events replay` queues one more delivery attempt and returns `{"object":"webhook_event","id":"<event-id>"}`; it does not schedule automatic retries.
  432. ```bash
  433. resend webhooks events list wh_abc123
  434. resend webhooks events list wh_abc123 --limit 50 --json
  435. resend webhooks events get wh_abc123 msg_1srOrx2ZWZBpBUvZwXKQmoEYga2
  436. resend webhooks events attempts wh_abc123 msg_1srOrx2ZWZBpBUvZwXKQmoEYga2
  437. resend webhooks events replay wh_abc123 msg_1srOrx2ZWZBpBUvZwXKQmoEYga2
  438. ```
  439. ---
  440. ### Inboxes
  441. With the Resend CLI, you can manage inboxes. An inbox is an email address at one of your verified domains that sends and receives email. Received emails are grouped into threads inside the inbox.
  442. Most inbox commands need a full-access API key. A sending-access key can run `threads emails reply`, `threads emails forward`, `drafts create`, and `drafts send`. A key limited to one domain must match the domain of the inbox. A sending-access key must pass every ID, because the ID pickers need full access.
  443. #### Subcommands
  444. - `list`
  445. - `create`
  446. - `get`
  447. - `update`
  448. - `delete`
  449. - `threads` (`list`, `search`, `get`, `update`, `delete`)
  450. - `threads labels` (`add`, `set`, `remove`)
  451. - `threads emails` (`list`, `get`, `reply`, `forward`)
  452. - `labels` (`list`, `create`, `update`, `delete`)
  453. - `drafts` (`list`, `create`, `get`, `update`, `delete`, `send`)
  454. - `agent` (`get`, `update`)
  455. #### Aliases
  456. - `inboxes ls` → `list`
  457. - `inboxes rm` → `delete`
  458. - `ls` and `rm` also work on `threads`, `threads emails` (`ls` only), `labels`, and `drafts`
  459. Running a group with no subcommand runs its `list`, or `get` for `agent`. `threads labels` shows its help.
  460. The nested commands take their IDs as positional arguments, parent first: the inbox ID, then the thread, draft, or label ID, then the email ID. For example, `resend inboxes threads emails get <inbox-id> <thread-id> <email-id>`. Each ID also has a flag, such as `--inbox-id` or `--thread-id`. Pass an ID as an argument or as a flag, not both.
  461. Every command that names an inbox takes its ID or its email address, such as `support@yourdomain.com`. The address match ignores case.
  462. In an interactive terminal without `--json` or `-q`, omit an ID to pick from a list. The exception is the email ID of `threads emails get`, `reply`, and `forward`. There, these commands ask you to type it. Get it from `threads emails list`.
  463. ---
  464. #### **`resend inboxes list`**
  465. Lists the inboxes of the team, newest first. Takes `--limit`, `--after`, and `--before`, like `resend webhooks list`.
  466. ```bash
  467. resend inboxes list
  468. resend inboxes list --limit 25 --json
  469. ```
  470. #### **`resend inboxes create`**
  471. Creates an inbox at an address on one of your domains. The part before the `@` can contain letters, numbers, and `. _ % -`, but not `+`. Without `--forwarding`, the domain must have receiving enabled. With `--forwarding`, Resend generates a receiving address, so you can receive mail without an MX record.
  472. The output holds only `{"object":"inbox","id":"<uuid>"}`. Run `resend inboxes get <id>` to read the other fields, such as `receiving_address`.
  473. | Flag | Description |
  474. | --------------------------- | --------------------------------------------------------------------- |
  475. | `--email-address <address>` | Inbox address — **required** in non-interactive mode |
  476. | `--name <name>` | Internal name, recipients do not see it |
  477. | `--from-name <name>` | Name recipients see when mail is sent from the inbox |
  478. | `--forwarding` | Receive mail without an MX record through a generated receiving address |
  479. ```bash
  480. resend inboxes create --email-address support@yourdomain.com
  481. resend inboxes create --email-address hello@yourdomain.com --name "Hello" --forwarding
  482. ```
  483. #### **`resend inboxes get`**
  484. Fetches one inbox by ID or by email address.
  485. ```bash
  486. resend inboxes get 78261eea-8f8b-4381-83c6-79fa7120f1cf
  487. resend inboxes get support@yourdomain.com --json
  488. ```
  489. #### **`resend inboxes update`**
  490. Updates the internal name or the from name. **At least one** of `--name` or `--from-name` is required. Pass `--from-name ""` to remove the from name.
  491. ```bash
  492. resend inboxes update 78261eea-8f8b-4381-83c6-79fa7120f1cf --name "Support"
  493. resend inboxes update 78261eea-8f8b-4381-83c6-79fa7120f1cf --from-name "Ada from Support"
  494. ```
  495. #### **`resend inboxes delete`**
  496. Deletes an inbox. In non-interactive mode, **`--yes` is required** to confirm.
  497. ```bash
  498. resend inboxes delete 78261eea-8f8b-4381-83c6-79fa7120f1cf --yes
  499. ```
  500. #### **`resend inboxes threads list`**
  501. Lists the threads in an inbox, most recently active first.
  502. | Flag | Description |
  503. | ------------------------- | --------------------------------------------------------------------------- |
  504. | `[inboxId]` or `--inbox-id <id>` | Inbox UUID or email address |
  505. | `--folders <folders...>` | `inbox`, `archive`, `spam`, `sent`, `trash` (default `inbox`, or `inbox archive sent` with `--labels`) |
  506. | `--labels <label-ids...>` | Label UUIDs. Returns threads with any of them |
  507. | `--read` / `--unread` | Only threads where every email is read, or with at least one unread email |
  508. | `--limit`, `--after`, `--before` | Pagination, with thread IDs as cursors |
  509. ```bash
  510. resend inboxes threads list <inbox-id>
  511. resend inboxes threads list <inbox-id> --folders inbox archive --unread --json
  512. ```
  513. #### **`resend inboxes threads search`**
  514. Finds threads by the text of their emails, who sent or received them, attachments, and dates. Takes `--query`, `--from`, `--to`, `--cc`, `--bcc`, `--has-attachment`, `--without-attachment`, `--start-date`, and `--end-date`, plus the filters and pagination of `threads list`. Each result has a `matched_email_id`, the ID of the email that matched. Pass it as the email ID of `threads emails get`, `reply`, and `forward`. Search can be up to about a minute behind new emails.
  515. ```bash
  516. resend inboxes threads search <inbox-id> --query invoice
  517. resend inboxes threads search <inbox-id> --from isabella@example.com --has-attachment --start-date 2026-09-01 --json
  518. ```
  519. #### **`resend inboxes threads get`**
  520. Fetches the summary of one thread. List its emails with `resend inboxes threads emails list`.
  521. ```bash
  522. resend inboxes threads get <inbox-id> <thread-id>
  523. ```
  524. #### **`resend inboxes threads update`**
  525. Marks a thread read or unread, or moves it to a folder. **At least one** option is required. To change the labels of a thread, use `threads labels`.
  526. | Flag | Description |
  527. | ------------------------------------ | -------------------------------------------------------- |
  528. | `--read` / `--unread` | Mark every email in the thread read or unread |
  529. | `--folder <folder>` | `inbox`, `archive`, `spam`, or `trash` |
  530. ```bash
  531. resend inboxes threads update <inbox-id> <thread-id> --read --folder archive
  532. ```
  533. #### **`resend inboxes threads delete`**
  534. Moves a thread to `trash` and schedules it for deletion in 30 days. To restore it, move it to another folder with `threads update --folder`. In non-interactive mode, **`--yes` is required**.
  535. ```bash
  536. resend inboxes threads delete <inbox-id> <thread-id> --yes
  537. ```
  538. #### **`resend inboxes threads labels add`**
  539. Adds labels to a thread. Labels already on the thread stay. **`--labels` is required** and takes 1 to 10 label IDs from `labels list`. The output lists every label on the thread after the change.
  540. ```bash
  541. resend inboxes threads labels add <inbox-id> <thread-id> --labels <label-id> <other-label-id>
  542. ```
  543. #### **`resend inboxes threads labels set`**
  544. Replaces every label on a thread in one atomic change. **`--labels` is required** and takes 0 to 100 label IDs. Pass `--labels ""` to remove every label. The labels themselves are kept. The output lists every label on the thread after the change.
  545. ```bash
  546. resend inboxes threads labels set <inbox-id> <thread-id> --labels <label-id>
  547. resend inboxes threads labels set <inbox-id> <thread-id> --labels ""
  548. ```
  549. #### **`resend inboxes threads labels remove`**
  550. Removes one label from a thread. The label itself is kept. The output lists every label on the thread after the change.
  551. ```bash
  552. resend inboxes threads labels remove <inbox-id> <thread-id> <label-id>
  553. ```
  554. #### **`resend inboxes threads emails list`**
  555. Lists the emails of a thread, oldest first, with their bodies. Takes `--limit`, `--after`, and `--before`, with email IDs as cursors.
  556. ```bash
  557. resend inboxes threads emails list <inbox-id> <thread-id>
  558. ```
  559. #### **`resend inboxes threads emails get`**
  560. Fetches one email of a thread.
  561. ```bash
  562. resend inboxes threads emails get <inbox-id> <thread-id> <email-id>
  563. ```
  564. #### **`resend inboxes threads emails reply`**
  565. Sends a reply from the inbox address. The reply goes to the `Reply-To` addresses of the email, or to its sender. If the inbox sent the email, the reply goes to its `to` recipients. `--reply-all` also copies the other recipients, without the inbox address and without duplicates. With `--reply-all`, a reply to an email the inbox sent goes to its `Reply-To` addresses when they are not the inbox address. **At least one** of `--text` or `--html` is required. The output holds the ID of the sent email.
  566. | Flag | Description |
  567. | --------------------------- | ------------------------------------------------------------ |
  568. | `--text <text>` | Plain-text body |
  569. | `--html <html>` | HTML body |
  570. | `--cc`, `--bcc <addresses...>` | Extra recipients, one or more |
  571. | `--subject <subject>` | Override the subject |
  572. | `--reply-all` | Reply to everyone on the original email |
  573. | `--attachment <specs...>` | File path or URL to attach, as on `resend emails send`. The content of all files can total at most 25 MB |
  574. | `--attachments-file <path>` | JSON array of attachment objects |
  575. | `--headers <key=value...>` | Custom headers. `In-Reply-To`, `References` and `Reply-To` are reserved. Names and values cannot contain line breaks |
  576. | `--idempotency-key <key>` | Deduplicate the send |
  577. ```bash
  578. resend inboxes threads emails reply <inbox-id> <thread-id> <email-id> --text "Thanks!"
  579. resend inboxes threads emails reply <inbox-id> <thread-id> <email-id> --text "Invoice attached." --attachment ./invoice.pdf
  580. ```
  581. #### **`resend inboxes threads emails forward`**
  582. Forwards an email from the inbox address. **`--to` is required.** The attachments of the original email are sent with the forward. Together with the files you add, they can have at most 25 MB of content. An original attachment that was sent from a URL cannot be forwarded. Takes `--cc`, `--bcc`, `--text`, `--html`, `--subject`, `--attachment`, `--attachments-file`, `--headers`, and `--idempotency-key`. The output holds the ID of the sent email.
  583. ```bash
  584. resend inboxes threads emails forward <inbox-id> <thread-id> <email-id> --to teammate@example.com --text "FYI"
  585. ```
  586. #### **`resend inboxes labels list`**
  587. Lists every label of an inbox, oldest first. The list is not paginated.
  588. ```bash
  589. resend inboxes labels list <inbox-id>
  590. ```
  591. #### **`resend inboxes labels create`**
  592. Creates a label. **`--name` is required.** `--color` takes a `#RRGGBB` hex color, random when omitted. Quote it so the shell keeps the `#`.
  593. ```bash
  594. resend inboxes labels create <inbox-id> --name "Urgent" --color '#E93D82'
  595. ```
  596. #### **`resend inboxes labels update`**
  597. Renames or recolors a label. **At least one** of `--name` or `--color` is required.
  598. ```bash
  599. resend inboxes labels update <inbox-id> <label-id> --name "Billing"
  600. ```
  601. #### **`resend inboxes labels delete`**
  602. Deletes a label and removes it from every thread. In non-interactive mode, **`--yes` is required**.
  603. ```bash
  604. resend inboxes labels delete <inbox-id> <label-id> --yes
  605. ```
  606. #### **`resend inboxes drafts list`**
  607. Lists the unsent drafts of an inbox, most recently updated first. Takes `--limit`, `--after`, and `--before`.
  608. ```bash
  609. resend inboxes drafts list <inbox-id>
  610. ```
  611. #### **`resend inboxes drafts create`**
  612. Creates a draft that starts a new thread. Pass `--thread-id` and `--reply-to-email-id` together for a reply draft. A reply draft without `--subject` is sent with the subject of the thread, prefixed with `Re:` when it does not already start with it. Takes `--to`, `--cc`, `--bcc`, `--subject`, `--text`, `--html`, `--attachment`, and `--attachments-file`. **At least one** of them is required. `--idempotency-key` deduplicates the request.
  613. `--attachment` takes a local file with `;type=<MIME type>`, or an `http://` or `https://` URL. A URL's filename defaults to the decoded last segment of its path and its MIME type to the type of the downloaded file. The URLs are downloaded when the draft is saved, so a URL that cannot be downloaded returns an error. The files on a draft can total at most 25 MB, downloads included.
  614. ```bash
  615. resend inboxes drafts create <inbox-id> --to user@example.com --subject "Hello" --text "Draft body"
  616. resend inboxes drafts create <inbox-id> --thread-id <thread-id> --reply-to-email-id <email-id> --text "Reply draft"
  617. resend inboxes drafts create <inbox-id> --to user@example.com --text "Report attached" --attachment "./report.pdf;type=application/pdf"
  618. resend inboxes drafts create <inbox-id> --to user@example.com --text "Invoice attached" --attachment "https://example.com/invoice.pdf"
  619. ```
  620. #### **`resend inboxes drafts get`**
  621. Fetches one draft with its full body.
  622. ```bash
  623. resend inboxes drafts get <inbox-id> <draft-id>
  624. ```
  625. #### **`resend inboxes drafts update`**
  626. Updates the recipients, subject, body, or attachments of an unsent draft. Setting `--text` or `--html` replaces the whole body. `--attachment` and `--attachments-file` replace every attachment on the draft, and `--clear-attachments` removes them all. `--attachment` and `--attachments-file` take the same local files and URLs as `drafts create`. `--clear-to`, `--clear-cc`, `--clear-bcc`, `--clear-subject`, `--clear-text`, and `--clear-html` remove the value of that field. A clear flag and a value for the same field return an error. The output holds only `{"object":"inbox_draft","id":"<uuid>"}`. Run `drafts get` to read the draft.
  627. ```bash
  628. resend inboxes drafts update <inbox-id> <draft-id> --subject "Updated subject"
  629. resend inboxes drafts update <inbox-id> <draft-id> --clear-attachments
  630. resend inboxes drafts update <inbox-id> <draft-id> --to ada@example.com grace@example.com --clear-cc
  631. ```
  632. #### **`resend inboxes drafts delete`**
  633. Discards an unsent draft. In non-interactive mode, **`--yes` is required**.
  634. ```bash
  635. resend inboxes drafts delete <inbox-id> <draft-id> --yes
  636. ```
  637. #### **`resend inboxes drafts send`**
  638. Sends a draft from the inbox address. The draft needs at least one `to` recipient and `html` or `text`. A standalone draft also needs a non-empty subject. A reply draft without a subject is sent with the subject of the thread, prefixed with `Re:` when it does not already start with it. `--headers` adds custom headers, except the reserved `In-Reply-To`, `References` and `Reply-To`. `--idempotency-key` deduplicates the send. The output holds the ID of the sent email.
  639. ```bash
  640. resend inboxes drafts send <inbox-id> <draft-id>
  641. ```
  642. #### **`resend inboxes agent get`**
  643. Fetches the agent settings of an inbox: `instructions`, `tone`, and `actions`.
  644. ```bash
  645. resend inboxes agent get <inbox-id>
  646. ```
  647. #### **`resend inboxes agent update`**
  648. Updates the agent settings. **At least one** of `--instructions`, `--tone`, or `--actions` is required. Omitted fields keep their current value. `--actions` replaces the whole set. It takes `draft_reply`, `forward_thread`, `add_labels`, `assign_thread`, `mark_as_spam`, `archive`, and `move_to_trash`.
  649. `--tone` takes one of the presets `concise_professional`, `concise_casual`, `expanded_professional`, or `expanded_casual`. Pass `--tone ""` to clear it. Other text returns `invalid_tone`.
  650. ```bash
  651. resend inboxes agent update <inbox-id> --tone concise_professional
  652. resend inboxes agent update <inbox-id> --actions draft_reply add_labels archive
  653. ```
  654. ---
  655. ## Global options
  656. These flags work on every command and are passed before the subcommand:
  657. ```bash
  658. resend [global options] <command> [command options]
  659. ```
  660. | Flag | Description |
  661. | ---------------------- | ------------------------------------------------------------- |
  662. | `--api-key <key>` | Override API key for this invocation (takes highest priority) |
  663. | `-p, --profile <name>` | Profile to use (overrides `RESEND_PROFILE` env var) |
  664. | `--json` | Force JSON output even in interactive terminals |
  665. | `-q, --quiet` | Suppress spinners and status output (implies `--json`) |
  666. | `--version` | Print version and exit |
  667. | `--help` | Show help text |
  668. ---
  669. ## Output behavior
  670. The CLI has two output modes:
  671. | Mode | When | Stdout | Stderr |
  672. | --------------- | ---------------------- | ------------------- | ---------------------------------------- |
  673. | **Interactive** | Terminal (TTY) | Formatted text | Spinners, prompts, human-readable errors |
  674. | **Machine** | Piped, CI, or `--json` | Success JSON only | JSON errors; optional warnings (e.g. flags) |
  675. Switching is automatic — pipe to another command and JSON output activates:
  676. ```bash
  677. resend doctor | jq '.checks[].name'
  678. resend emails send --from ... --to ... --subject ... --text ... | jq '.id'
  679. ```
  680. ### Error output
  681. Errors always exit with code `1`. The format on **stderr** depends on output mode (same rules as the table above):
  682. - **Machine** (piped stdout, CI, `--json`, or `-q`): structured JSON so **stdout** stays success-only for scripting (`jq`, etc.):
  683. ```json
  684. { "error": { "message": "No API key found", "code": "auth_error" } }
  685. ```
  686. - **Interactive** (TTY without `--json` / `-q`): a human-readable line such as `Error: No API key found` (still on stderr).
  687. ---
  688. ## Agent & CI/CD usage
  689. ### CI/CD
  690. Set `RESEND_API_KEY` as an environment variable — no `resend login` needed:
  691. ```yaml
  692. # GitHub Actions
  693. env:
  694. RESEND_API_KEY: ${{ secrets.RESEND_API_KEY }}
  695. steps:
  696. - run: |
  697. resend emails send \
  698. --from "deploy@example.com" \
  699. --to "delivered@resend.dev" \
  700. --subject "Deploy complete" \
  701. --text "Version ${{ github.sha }} deployed."
  702. ```
  703. ### AI agents
  704. Agents calling the CLI as a subprocess automatically get JSON output (non-TTY detection). The contract:
  705. - **Input:** All required flags must be provided (no interactive prompts)
  706. - **Output:** Success JSON on stdout; error JSON on stderr (use `2>` or combined capture if you need both)
  707. - **Exit code:** `0` success, `1` error
  708. - **Errors:** Always include `message` and `code` fields
  709. - **Discovery:** `resend commands` prints the full command tree as JSON (subcommands, options, descriptions).
  710. ### `resend commands`
  711. Prints the CLI command tree as JSON for scripting and AI agents. In an interactive terminal, pass global `--json` if you need machine output; when stdout is piped, JSON is used automatically.
  712. ---
  713. ## Dry-run (no API call)
  714. `--dry-run` validates a payload and prints it without calling the API. These commands support it:
  715. - **`resend emails send ... --dry-run`** — validates inputs and prints `{ "dryRun": true, "request": { ... } }` without sending. Attachments appear as `filename` and `byteLength` only.
  716. - **`resend broadcasts create ... --dry-run`** — same for the broadcast create payload.
  717. - **`resend emails batch --file ./emails.json --dry-run`** — parses and normalises the JSON array, resolves any `--react-email` template, then prints the request payload without sending. No API key required.
  718. Other commands do not support `--dry-run`.
  719. ---
  720. ## Configuration
  721. | Item | Path | Notes |
  722. | ----------------- | ----------------------------------- | ------------------------------------------------------------ |
  723. | Config directory | `~/.config/resend/` | Respects `$XDG_CONFIG_HOME` on Linux, `%APPDATA%` on Windows |
  724. | Credentials | `~/.config/resend/credentials.json` | `0600` permissions (owner read/write) |
  725. | Install directory | `~/.resend/bin/` | Respects `$RESEND_INSTALL` |
  726. ## License
  727. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.