https://github.com/paperfoot/email-cli
Send, receive, and manage email from your terminal. Built for AI agents. Resend API, local SQLite mailbox, RFC 5322 threading, 50+ commands.
https://github.com/paperfoot/email-cli
ai-agent-tools ai-agents automation cli command-line-tool developer-tools devtools email email-api email-automation email-cli email-threading local-first resend resend-api rfc-5322 rust rust-cli send-email sqlite
Last synced: 9 days ago
JSON representation
Send, receive, and manage email from your terminal. Built for AI agents. Resend API, local SQLite mailbox, RFC 5322 threading, 50+ commands.
- Host: GitHub
- URL: https://github.com/paperfoot/email-cli
- Owner: paperfoot
- License: mit
- Created: 2026-03-12T13:20:48.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-17T20:43:03.000Z (10 days ago)
- Last Synced: 2026-04-17T22:29:22.265Z (9 days ago)
- Topics: ai-agent-tools, ai-agents, automation, cli, command-line-tool, developer-tools, devtools, email, email-api, email-automation, email-cli, email-threading, local-first, resend, resend-api, rfc-5322, rust, rust-cli, send-email, sqlite
- Language: Rust
- Size: 437 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Email CLI
**Send, receive, and manage email from your terminal. Built for AI agents.**
[](https://github.com/paperfoot/email-cli/stargazers)
[](https://x.com/longevityboris)
[](https://crates.io/crates/email-cli)
[](LICENSE)
[](https://www.rust-lang.org/)
[](https://github.com/199-biotechnologies/homebrew-tap)
---
A single binary that gives your AI agent a real email address. Send, receive, reply, draft, sync, and manage contacts, broadcasts, segments, and topics through Resend -- all from the command line. No IMAP. No browser inbox. No MCP server. Just a local SQLite mailbox and 70+ commands.
[Why This Exists](#why-this-exists) | [Install](#install) | [How It Works](#how-it-works) | [Commands](#commands) | [Mailing-list Workflows](#mailing-list-workflows) | [Configuration](#configuration) | [Contributing](#contributing)
## Why This Exists
AI agents need to send and receive email. The existing options are bad:
- **IMAP/SMTP** requires complex server configuration, credential management, and connection handling. Agents struggle with it.
- **Email APIs** work for sending, but agents need a local mailbox to track threads, drafts, and read status.
- **Browser-based inboxes** are not scriptable. Agents cannot use them.
Email CLI solves this by wrapping the [Resend API](https://resend.com) in a local-first CLI. Your agent gets a verified email address, a local SQLite mailbox, and structured JSON output with semantic exit codes. It calls `agent-info` once to learn every command, then works from memory.
You can also use it as a human. It works the same way.
## Install
### One-line install (pre-built binary, no Rust required)
```bash
curl -fsSL https://raw.githubusercontent.com/paperfoot/email-cli/main/install.sh | sh
```
### Homebrew
```bash
brew tap 199-biotechnologies/tap
brew install email-cli
```
### Cargo
```bash
cargo install email-cli
```
### Update
```bash
email-cli update # self-update from GitHub Releases
email-cli update --check # check without installing
```
## Quick Start
```bash
# 1. Add your Resend API key
email-cli profile add default --api-key-env RESEND_API_KEY
# 2. Verify domain connectivity
email-cli profile test default
# 3. Register a sending identity
email-cli account add agent@yourdomain.com \
--profile default \
--name "Agent" \
--default
# 4. Send an email
email-cli send \
--to someone@example.com \
--subject "Hello from email-cli" \
--text "Sent from the terminal."
# 5. Sync and read incoming mail
email-cli sync
email-cli inbox ls
email-cli inbox read 1 --mark-read
# 6. Reply (threads correctly with In-Reply-To + References)
email-cli reply 1 --text "Got it, thanks."
# 7. Reply All (preserves CC recipients)
email-cli reply 1 --all --text "Thanks everyone."
# 8. Forward
email-cli forward 1 --to colleague@example.com --text "FYI"
# 9. Thread a new send into an existing conversation
email-cli send --reply-to-msg 1 --to someone@example.com --text "Following up"
```
## How It Works
Three concepts:
1. **Profile** -- a Resend API key. You can have multiple profiles for different Resend accounts.
2. **Account** -- a sender/receiver identity (`agent@yourdomain.com`). Each account belongs to a profile.
3. **Local mailbox** -- a SQLite database that stores messages, drafts, attachments, and sync cursors.
Resend handles delivery. Email CLI handles the local operating model that agents need: read tracking, threading, drafts, batch sends, and structured output.
```
┌────────────────────────────────┐
│ Your Agent / You │
│ (Claude, Codex, Gemini) │
└──────────────┬─────────────────┘
│ CLI commands
▼
┌────────────────────────────────┐
│ email-cli │
│ 50+ commands, JSON output, │
│ semantic exit codes │
└──────────┬─────────┬───────────┘
│ │
┌─────▼──┐ ┌───▼────────┐
│ SQLite │ │ Resend API │
│ local │ │ (send, │
│ store │ │ receive, │
│ │ │ domains) │
└────────┘ └────────────┘
```
## Commands
### Core Email
| Command | What it does |
|---|---|
| `send` | Send email (--reply-to-msg for threading, --cc, --bcc, --attach) |
| `reply ` | Reply with proper threading headers (--all for Reply All) |
| `forward ` | Forward a message (--to, --cc, --text for preamble) |
| `sync` | Pull sent and received messages into local store |
| `inbox ls` | List messages (filter by account, unread status) |
| `inbox read ` | Read a message, optionally mark as read |
| `inbox search ` | Search messages by keyword |
| `inbox delete ` | Delete a message |
| `inbox archive ` | Archive a message |
| `draft create` | Save a local draft with attachment snapshots |
| `draft list` | List all drafts |
| `draft show ` | View draft details |
| `draft edit ` | Edit a draft |
| `draft send ` | Send a draft and delete it |
| `draft delete ` | Delete a draft |
| `attachments list ` | List attachments on a message |
| `attachments get ` | Download an attachment to disk |
### Account Management
| Command | What it does |
|---|---|
| `profile add ` | Add or update a Resend API profile |
| `profile list` | List all profiles |
| `profile test ` | Test API connectivity |
| `account add ` | Register an email identity |
| `account list` | List all accounts |
| `account use ` | Set the default sending account |
| `signature set ` | Set per-account signature |
| `signature show ` | Show signature |
### Resend Management
| Command | What it does |
|---|---|
| `domain list` | List your Resend domains |
| `domain get ` | Get domain details with DNS records |
| `domain create --name ` | Register a new domain |
| `domain verify ` | Trigger domain verification |
| `domain delete ` | Delete a domain |
| `domain update ` | Update tracking settings |
| `batch send --file ` | Send batch emails from a JSON file |
| `email list` | List sent emails via Resend GET /emails (each row includes `last_event` for polling) |
| `api-key list` | List API keys |
| `api-key create --name ` | Create an API key |
| `api-key delete ` | Delete an API key |
### The Audience Section
In the Resend dashboard, "Audience" is the section name in the left sidebar. It groups four primitives — **Contacts**, **Properties**, **Segments**, and **Topics** — each with its own CLI command in email-cli:
| Resend dashboard tab | email-cli command | Purpose |
|---|---|---|
| Contacts | `contact` | Individual email addresses |
| Properties | `contact-property` | Typed custom-field schemas (e.g. `company`, `plan`) |
| Segments | `segment` | Groupings of contacts (a contact can be in multiple segments) |
| Topics | `topic` | User-facing subscription preferences for broadcasts |
> The pre-November-2025 "Audiences as a grouping primitive" model has been replaced. Contacts are now flat — each contact can belong to zero, one, or multiple segments. There is no `audience` noun in this CLI; use `segment` instead.
### Contacts
| Command | What it does |
|---|---|
| `contact list` | List contacts (`--limit` 1-100, `--after ` for cursor pagination) |
| `contact get ` | Get a contact by id or email (surfaces custom properties) |
| `contact create --email ` | Create a contact (`--first-name`, `--last-name`, `--unsubscribed`, `--properties '{"k":"v"}'`, `--segments seg1,seg2`, `--topics top_xxx:opt_in,top_yyy:opt_out`) |
| `contact update ` | Update contact fields (`--first-name`, `--last-name`, `--unsubscribed`, `--properties`) |
| `contact delete ` | Delete a contact |
### Segments
| Command | What it does |
|---|---|
| `segment list` | List segments |
| `segment get ` | Get segment details |
| `segment create --name ` | Create a segment |
| `segment delete ` | Delete a segment |
| `segment contacts ` | List the contacts in a segment |
| `segment contact-add --contact --segment ` | Add a contact to a segment |
| `segment contact-remove --contact --segment ` | Remove a contact from a segment |
| `segment contact-list --contact ` | List the segments a contact belongs to |
### Custom Contact Properties
Resend's contact properties are typed key/value fields you attach to contacts. Use them for merge tags in broadcasts and templates. **You must define a property's schema before assigning values to a contact.**
| Command | What it does |
|---|---|
| `contact-property list` | List defined contact-property schemas |
| `contact-property get ` | Get a contact-property schema |
| `contact-property create --key company --property-type string` | Define a property (`--fallback` for default value, `--property-type` `string`/`number`) |
| `contact-property update --fallback "N/A"` | Update a property's fallback value (add `--as-number` if the property is numeric) |
| `contact-property delete ` | Delete a contact-property schema |
| `contact create --properties '{"company":"Acme","plan":"pro"}'` | Assign property values when creating a contact |
### Topics (Granular Subscription Preferences)
Topics power Resend's granular unsubscribe flow on broadcasts. Each contact can be opted in or out of any topic, and broadcasts wired to a topic auto-substitute the right unsubscribe URL.
| Command | What it does |
|---|---|
| `topic list` | List topics |
| `topic get ` | Get topic details |
| `topic create --name "Weekly Digest"` | Create a topic (`--description`, `--default-subscription opt_in`/`opt_out`, `--visibility public`/`private`) |
| `topic update ` | Update topic fields (`--name`, `--description`, `--default-subscription`, `--visibility`) |
| `topic delete ` | Delete a topic |
| `topic contact-set --contact --topic --subscription opt_in` | Subscribe or unsubscribe a contact |
| `topic contact-list --contact ` | List a contact's topic subscriptions |
### Broadcasts
Broadcasts are Resend's native campaign sending. Use these instead of `batch send` when you want auto unsubscribe wiring (`{{{RESEND_UNSUBSCRIBE_URL}}}`), server-side scheduling, and Resend's internal queue throttling.
| Command | What it does |
|---|---|
| `broadcast list` | List broadcasts |
| `broadcast get ` | Get broadcast details |
| `broadcast create --segment-id --from --subject --html ` | Create a broadcast (`--text`, `--name`, `--reply-to`, `--topic-id`, `--scheduled-at`, `--send` for inline send). `--audience-id` is accepted as a legacy alias. |
| `broadcast update ` | Update a draft broadcast (`--segment-id`, `--from`, `--subject`, `--html`, `--text`, `--name`, `--reply-to`, `--topic-id`) |
| `broadcast send ` | Send (or schedule via `--scheduled-at`) |
| `broadcast delete ` | Delete (cancels scheduled broadcasts) |
### Agent Tooling
| Command | What it does |
|---|---|
| `agent-info` | Machine-readable JSON capability manifest |
| `skill install` | Install skill file for Claude/Codex/Gemini |
| `skill status` | Check skill installation status |
| `completions ` | Generate shell completions (bash/zsh/fish) |
## Mailing-list Workflows
Email CLI is the Resend client for [`mailing-list-cli`](https://github.com/paperfoot/mailing-list-cli) and any other tool that needs to wrap a complete mailing-list workflow on top of Resend. Three primitives matter:
1. **Segments** group contacts. (Audiences, in pre-November-2025 terms.)
2. **Contact properties** are typed custom fields on each contact. Define the schema, then assign values.
3. **Topics** drive granular per-contact subscription preferences for broadcasts.
### End-to-end example
```bash
# 1. Define a custom field schema (do this once per property)
email-cli contact-property create --key company --property-type string
email-cli contact-property create --key plan --property-type string --fallback "free"
# 2. Create a topic for granular unsubscribes
email-cli topic create --name "Weekly Digest" --default-subscription opt_in
# → returns topic id, e.g. top_xyz
# 3. Create a segment to group contacts
email-cli segment create --name "Beta users"
# → returns segment id, e.g. seg_abc123
# 4. Add a contact with custom properties and add them to the segment in one shot
email-cli contact create \
--email alice@example.com \
--first-name Alice \
--properties '{"company":"Acme","plan":"pro"}' \
--segments seg_abc123
# 5. Subscribe the contact to the topic
email-cli topic contact-set \
--contact alice@example.com \
--topic top_xyz \
--subscription opt_in
# 6. Create and send a broadcast (auto unsubscribe URL via {{{RESEND_UNSUBSCRIBE_URL}}})
email-cli broadcast create \
--segment-id seg_abc123 \
--topic-id top_xyz \
--from "Acme " \
--subject "This week at Acme" \
--html '
Hi {{first_name}},
Latest digest...
'
# → returns broadcast id, e.g. brd_456
email-cli broadcast send brd_456
# 7. Poll delivery status (replaces a webhook listener for the basic case)
email-cli email list --limit 100
```
> Note: Wiring `--topic-id` on the broadcast tells Resend which topic the unsubscribe link should opt the recipient out of. Without `--topic-id`, the unsubscribe URL still works but uses an account-wide unsubscribe.
### Why polling beats running a second webhook listener
`email list` returns each email's `last_event` (`sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked`). For the suppression-driving path -- delivered/bounced/complained -- polling is enough and avoids the operational cost of a second webhook URL pointed at your tool. For full engagement history (open → click → unsubscribe), keep using `webhook listen` -- it stores every event into the local SQLite events table, which `events list` queries.
## Email Threading
Every outgoing email gets a unique `Message-ID` header (``). Replies set `In-Reply-To` and `References` per RFC 5322, so threads display correctly in Gmail, Outlook, and Apple Mail.
| Action | Headers Set | Threading |
|---|---|---|
| `send` | Message-ID | New conversation |
| `send --reply-to-msg ` | Message-ID, In-Reply-To, References | Threads into existing conversation |
| `reply ` | Message-ID, In-Reply-To, References | Threads into existing conversation |
| `reply --all` | Same + preserves CC | Threads with all recipients |
| `forward ` | Message-ID only | New conversation (per RFC) |
## Agent Integration
Email CLI follows the [agent-cli-framework](https://github.com/paperfoot/agent-cli-framework) patterns. Any agent that speaks structured JSON can use it.
### Capability Discovery
```bash
email-cli agent-info
```
Returns a JSON manifest of every command, flag, exit code, and output format. An agent calls this once and works from memory.
### Structured Output
All commands produce JSON when piped or when you pass `--json`:
```json
{
"version": "1",
"status": "success",
"data": { ... }
}
```
Errors include actionable suggestions:
```json
{
"version": "1",
"status": "error",
"error": {
"code": "config_error",
"message": "no default account configured",
"suggestion": "Run profile add / account add to configure"
}
}
```
### Semantic Exit Codes
| Code | Meaning | Agent action |
|---|---|---|
| 0 | Success | Continue |
| 1 | Transient error (network) | Retry |
| 2 | Configuration error | Fix setup |
| 3 | Bad input | Fix arguments |
| 4 | Rate limited | Wait and retry |
### Skill Self-Install
```bash
email-cli skill install
```
Writes a skill file to `~/.claude/skills/email-cli/`, `~/.codex/skills/email-cli/`, and `~/.gemini/skills/email-cli/`. The skill tells agents the CLI exists and to run `agent-info` for full details.
## Configuration
### Local State
All data lives in `~/.local/share/email-cli/email-cli.db` (override with `--db `). Sibling directories:
- `draft-attachments/` -- snapshots of files attached to drafts
- `downloads/` -- fetched attachments (configurable via `--output`)
### Database Tables
| Table | Purpose |
|---|---|
| `profiles` | API key storage |
| `accounts` | Email identities with signatures |
| `messages` | Sent and received email with full metadata |
| `drafts` | Local drafts with attachment snapshots |
| `attachments` | Attachment metadata and local file paths |
| `sync_state` | Per-account sync cursor positions |
SQLite runs with WAL mode, busy timeout, and foreign keys enabled.
### Security
- API keys live in the local SQLite database. Treat `email-cli.db` as sensitive.
- Use `--api-key-env VAR_NAME` or `--api-key-file path` instead of passing keys directly.
- Attachment filenames are sanitized before writing to disk.
- Each send includes a UUID `Idempotency-Key` header.
### Requirements
- A [Resend](https://resend.com) API key with sending enabled
- A verified Resend domain (enable receiving on the domain for inbox sync)
- Rust 1.85+ if building from source (edition 2024)
## Contributing
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
MIT -- see [LICENSE](LICENSE).
---
Built by [Boris Djordjevic](https://github.com/longevityboris) at [199 Biotechnologies](https://github.com/199-biotechnologies) | [Paperfoot AI](https://paperfoot.ai)
**If this is useful to you:**
[](https://github.com/paperfoot/email-cli/stargazers)
[](https://x.com/longevityboris)