email

What this skill does

# Email CLI

Send emails using the `email-cli` command.

## Quick Start

```bash
# Send a simple email
email-cli send -t [email protected] -s "Subject" -m "Message body"

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

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

## Common Patterns

### Send to multiple recipients
```bash
email-cli send -t [email protected] -t [email protected] -s "Team Update" -m "Hello team"
```

### HTML email
```bash
email-cli send -t [email protected] -s "Newsletter" -m "<h1>Hello</h1>" --html
```

### Use specific provider
```bash
email-cli send -p work -t [email protected] -s "Subject" -m "Body"
```

## Configuration

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

```bash
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):**
```bash
email-cli config add --name agent \
  --type agentmail \
  --api-key "am_..." \
  --inbox-id "[email protected]" \
  --default
```

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

**Gmail (lowest friction for existing accounts):**
```bash
email-cli config add --name gmail-smtp \
  --type smtp \
  --from [email protected] \
  --host smtp.gmail.com \
  --port 587 \
  --username [email protected] \
  --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:**
```bash
email-cli config add --name mymail \
  --type smtp \
  --from [email protected] \
  --host smtp.example.com \
  --port 587 \
  --username [email protected] \
  --password "password" \
  --tls
```

**Proton Mail:**
```bash
email-cli config add --name proton \
  --type proton \
  --from [email protected] \
  --username [email protected] \
  --password "bridge-password"
```

**Google API (only when explicitly requested):**
```bash
email-cli config add --name google \
  --type google \
  --from [email protected] \
  --client-id "xxx.apps.googleusercontent.com" \
  --client-secret "xxx"
```

### Update config
```bash
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 "[email protected]" --use-keychain
email-cli config set --use-keychain mymail password "new-password"
```

### View config as JSON
```bash
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.