email-cli

email-cli

A simple CLI for agents to send emails. Supports AgentMail, Google Workspace, Proton Mail, and generic SMTP.

Install

Install Script (requires Go)

curl -fsSL https://raw.githubusercontent.com/tnm/email-cli/main/email/install.sh | bash

Installs email-cli into ~/.local/bin by default. If that directory is not on your PATH:

export PATH="$HOME/.local/bin:$PATH"

Or install from a local checkout:

git clone https://github.com/tnm/email-cli
cd email-cli/email
./install.sh

Go Install

go install github.com/tnm/email-cli@latest

Or build from source:

git clone https://github.com/tnm/email-cli
cd email-cli/email
go build -o email-cli .

Claude Code Plugin

Install as a Claude Code plugin for AI agent access:

# Add the marketplace
/plugin marketplace add tnm/email-cli

# Install the plugin
/plugin install email-cli@email-cli

# Or load locally during development
claude --plugin-dir /path/to/email-cli

Once installed, Claude automatically uses email-cli when you ask it to send emails.

Quick Start

# Add a provider (interactive)
email-cli config add mymail

# Send an email
email-cli send -t recipient@example.com -s "Hello" -m "Message body"

---

Configuration

Config is stored at ~/.config/email-cli/config.json

Security

email-cli follows a pragmatic local-file security model:

• Secrets are stored in plaintext in ~/.config/email-cli/config.json by default.
• On macOS, you can use --use-keychain to store secrets in macOS Keychain instead.
• File permissions are restricted to owner-only (0600) when writing config.
• email-cli config show redacts secrets by default.
• email-cli config show --show-secrets prints raw secrets and should be treated as sensitive.

macOS Keychain Support

On macOS, you can store secrets in the system Keychain instead of the config file:

# Store credentials in Keychain when adding a provider
email-cli config add --name agent \
  --type agentmail \
  --api-key "am_..." \
  --inbox-id "myagent@agentmail.to" \
  --use-keychain

# Update a secret and store in Keychain
email-cli config set --use-keychain mymail password "new-password"

When using Keychain, the config file stores a reference like keychain:mymail/password instead of the actual secret. The secret is resolved from Keychain at runtime.

Benefits:

• Secrets never appear in the config file
• Protected by macOS Keychain security (Touch ID, password, etc.)
• Secrets survive config file inspection

Note: Keychain support is only available on macOS.

Operational Guidance

• Avoid passing secrets directly on command lines when possible (--api-key, --password, --access-token, --refresh-token) because shell history and process inspection may expose them.
• Use --use-keychain on macOS for sensitive credentials.
• Prefer app-specific passwords for SMTP providers (for Gmail, use an App Password).
• Rotate credentials immediately if a machine, shell history, or agent transcript is exposed.
• For install safety, prefer reviewing install.sh from a pinned version tag before running it.

Interactive Mode (for humans)

email-cli config add mymail

Walks you through provider selection and credential entry.

Non-Interactive Mode (for scripts/agents)

AgentMail (easiest - just API key)

email-cli config add --name agent \
  --type agentmail \
  --api-key "am_..." \
  --inbox-id "myagent@agentmail.to" \
  --default

No OAuth, no app passwords, no local servers. Just an API key from agentmail.to. Free tier: 3 inboxes, 3k emails/month.

Recommended for Gmail (lowest friction): SMTP + App Password

email-cli config add --name gmail-smtp \
  --type smtp \
  --from me@gmail.com \
  --host smtp.gmail.com \
  --port 587 \
  --username me@gmail.com \
  --password "$GMAIL_APP_PASSWORD" \
  --tls \
  --default

Use this when you want the fastest setup for humans and agents. It avoids Google Cloud OAuth client setup.

SMTP

email-cli config add --name mymail \
  --type smtp \
  --from me@example.com \
  --host smtp.example.com \
  --port 587 \
  --username me@example.com \
  --password "secret" \
  --tls

Proton Mail

email-cli config add --name proton \
  --type proton \
  --from me@proton.me \
  --username me@proton.me \
  --password "bridge-password"

Google Workspace (Gmail API)

email-cli config add --name google \
  --type google \
  --from me@gmail.com \
  --client-id "xxx.apps.googleusercontent.com" \
  --client-secret "xxx"

By default this starts OAuth device flow and prints a verification URL/code in your terminal. To force localhost callback flow instead:

email-cli config add --name google \
  --type google \
  --from me@gmail.com \
  --client-id "xxx.apps.googleusercontent.com" \
  --client-secret "xxx" \
  --oauth-method local