✉️ Stellamail

Safe email CLI for AI agents and humans.

Built with safety rails that prevent the disasters AI agents cause with email — duplicate sends, missing attachments, forgotten CCs. Works great as a standalone terminal email client too.

Install

npm install -g stellamail

Quick Start

# Interactive setup wizard
stellamail init

# Check your inbox
stellamail inbox --account work

# Send an email
stellamail send --account work \
  --to "[email protected]" \
  --cc "[email protected]" \
  --subject "Report attached" \
  --body "Hi, please find your report attached." \
  --attachment "/path/to/report.pdf"

# Or grab the most recent matching file
stellamail send --account work \
  --to "[email protected]" \
  --cc "[email protected]" \
  --subject "Latest report attached" \
  --body-file /tmp/email.txt \
  --recent --recent-pattern "radon,pdf"

# Read a message
stellamail read 42 --account work

# Reply
stellamail reply 42 --account work --body "Thanks for the update!"

Commands

| Command | Description | |---------|-------------| | send | Send an email | | reply <id> | Reply to an email | | forward <id> | Forward an email | | inbox | List inbox messages | | read <id> | Read a single email | | search | Search emails | | folders | List mailbox folders | | move <id> | Move a message to another folder | | delete <id> | Delete a message | | flag <id> | Toggle flags on a message | | log | View send log | | test | Test SMTP/IMAP connections | | accounts | List configured accounts | | templates | List available templates | | init | Interactive setup wizard |

Safety Features

These aren't optional — they're the whole point.

• 🔒 Duplicate blocking — Same email within 24h? Blocked. Configurable cooldown.
• ✅ Attachment validation — PDF header check, file exists, size limits.
• 📋 CC enforcement — Per-account. Can't "forget" to CC the boss.
• 📝 Send logging — Every send logged with timestamp, recipient, status.
• 🚫 One attempt only — No retries. Ever. Fail = report and stop.
• 🧪 Dry run — Preview everything before sending with --dry-run.

Templates

Define reusable email templates in your config:

stellamail send --account work \
  --template report-delivery \
  --var firstName=Sarah \
  --var reportType=Radon \
  --var address="123 Main St" \
  --attachment report.pdf

Signatures

Per-account signatures with template variables:

{
  "signature": {
    "text": "\n--\n{{name}}\n{{title}}\n{{company}}",
    "vars": {
      "name": "Jane Smith",
      "title": "Inspector",
      "company": "Acme Inspections"
    }
  }
}

Skip with --no-signature.

Draft Flow

You can save a draft first, inspect it, and send it later:

stellamail draft save \
  --account work \
  --to "[email protected]" \
  --subject "Report attached" \
  --body-file /tmp/email.txt \
  --attachment /path/to/report.pdf

stellamail draft list
stellamail draft show <draft_id>
stellamail send --draft <draft_id> --dry-run
stellamail send --draft <draft_id>

Agent-Friendly Notes

Stellamail is designed to be safe for agents too:

• Prefer --dry-run first when generating outbound email from an AI workflow
• Use --body-file when the message body is multi-paragraph or generated elsewhere
• Use --recent --recent-pattern ... when the attachment path is obvious but annoying to type
• Every major command supports --output json for clean machine-readable output
• Plain text bodies preserve real spacing and also generate a clean HTML version automatically
• Dry-run previews now show the full body and attachment details so agents can verify exactly what will send

JSON Output

Every command supports --output json for scripting and AI agent integration:

stellamail inbox --account work --output json
stellamail accounts --output json

Configuration

Run stellamail init for interactive setup, or create ~/.stellamail.config.json manually. See config-example.json for all options.

Security:

• Config file auto-set to chmod 600
• Warning if permissions are too open
• Environment variable override: STELLAMAIL_ACCOUNTNAME_PASS

Why Stellamail?

An AI agent sent 15 duplicate emails to a client at midnight. The home inspector woke up to an inbox full of angry replies. That's why.

Stellamail was born out of pure frustration — built by a New Jersey home inspector who just wanted his AI assistant to send one email. ONE. Instead, it sent fifteen. So he built an email tool his bots literally can't break.

Duplicate blocking, attachment validation, and CC enforcement aren't features — they're therapy.

But it's also just a really nice terminal email client for humans. Color-coded inbox, clean formatting, fast IMAP. No Electron, no bloat, no nonsense.

Tech

• SMTP: nodemailer
• IMAP: imapflow
• Parsing: mailparser
• UI: chalk + cli-table3
• Config: JSON (no database)
• Runtime: Node.js (CommonJS)

License

MIT