email

name	email
description	Send emails via CLI. Use when the user asks to send an email, compose a message, or needs email functionality. Supports AgentMail, Google Workspace, Proton Mail, and generic SMTP.

Email CLI

Send emails using the email-cli command.

Quick Start

# Send a simple email
email-cli send -t [e-mail] -s "Subject" -m "Message body"

# Send with attachment
email-cli send -t [e-mail] -s "Report" -m "See attached" -a report.pdf

# Pipe content from stdin
echo "Generated content" | email-cli send -t [e-mail] -s "Report"

Common Patterns

Send to multiple recipients

email-cli send -t [e-mail] -t [e-mail] -s "Team Update" -m "Hello team"

HTML email

email-cli send -t [e-mail] -s "Newsletter" -m "<h1>Hello</h1>" --html

Use specific provider

email-cli send -p work -t [e-mail] -s "Subject" -m "Body"

Configuration

Before sending, a provider must be configured. Check existing config:

email-cli config list

Recommended decision order (for agents)

1. AgentMail first — easiest, just needs API key + inbox ID
2. For existing email accounts, try SMTP
3. For Gmail, prefer smtp.gmail.com with an App Password
4. Only use Google API OAuth if the user explicitly asks for Gmail API/OAuth
5. Use Proton only for Proton Mail Bridge users

Add provider (non-interactive, for agents)

AgentMail (easiest - no OAuth, no app passwords):

email-cli config add --name agent \
  --type agentmail \
  --api-key "am_..." \
  --inbox-id "[e-mail]" \
  --default

Get API key and create inbox at agentmail.to. Free tier: 3 inboxes, 3k emails/month.

Gmail (lowest friction for existing accounts):

email-cli config add --name gmail-smtp \
  --type smtp \
  --from [e-mail] \
  --host smtp.gmail.com \
  --port 587 \
  --username [e-mail] \
  --password "$GMAIL_APP_PASSWORD" \
  --tls \
  --default

If user does not have an app password yet:

• Ask them to enable 2-Step Verification.
• Ask them to generate an app password at https://myaccount.google.com/apppasswords.
• Then run the command above.

SMTP:

email-cli config add --name mymail \
  --type smtp \
  --from [e-mail] \
  --host smtp.example.com \
  --port 587 \
  --username [e-mail] \
  --password "password" \
  --tls

Proton Mail:

email-cli config add --name proton \
  --type proton \
  --from [e-mail] \
  --username [e-mail] \
  --password "bridge-password"

Google API (only when explicitly requested):

email-cli config add --name google \
  --type google \
  --from [e-mail] \
  --client-id "xxx.apps.googleusercontent.com" \
  --client-secret "xxx"

Update config

email-cli config set mymail password "new-password"
email-cli config set agent api-key "new-api-key"

# Store secrets in macOS Keychain (optional, macOS only)
email-cli config add --name agent --type agentmail --api-key "am_..." --inbox-id "[e-mail]" --use-keychain
email-cli config set --use-keychain mymail password "new-password"

View config as JSON

email-cli config show                     # redacted by default
email-cli config show mymail              # redacted by default
email-cli config show --show-secrets      # with secrets
email-cli config show --show-secrets mymail

Exit Codes

• 0 = Success
• 1 = Error (check stderr for details)

Reference

See reference.md for complete API documentation.