Manage Email

Interact with your email inbox using mail-cli commands: read, search, send, reply, mark, move, delete, manage folders, drafts, and accounts via CLI.

Security Scan

The skill's instructions match its stated purpose (managing email via a CLI) but it advises installing an unverified npm package and would let the agent run commands that access your mailbox and files — those installation and runtime implications are noteworthy and merit caution.

Purpose & Capability

The name/description (Manage Email via mail-cli) align with the runtime instructions: all examples and workflows are about reading, searching, sending, and managing email via a 'mail-cli' tool.

Instruction Scope

SKILL.md stays within the email-management domain and does not instruct reading arbitrary system files or unrelated environment variables. It does instruct running mail-cli commands that may download attachments to disk and attach local files, and it includes an npm install example; those runtime actions will access mailbox data and the filesystem and should be expected and monitored.

Install Mechanism

Although the registry has no formal install spec, the SKILL.md explicitly recommends 'npm install -g @laffy1309/emailcli'. That is an unsigned, third-party package name (unknown author) and a global npm install can run arbitrary code on the host. This is the primary risk signal.

Credentials

The skill declares no required env vars or credentials and expects local mail-cli account configuration (e.g., 'mail-cli account add') to provide provider auth. That is proportionate, but the skill does not document how OAuth/credentials are handled; attachments and mailbox access mean sensitive data will be reachable by the CLI and by any agent-run processes.

Persistence & Privilege

always is false and the skill does not request persistent or system-wide configuration changes in the manifest. Autonomous invocation is allowed (platform default) but not combined with other high-privilege requests in the manifest.

What to consider before installing

Before installing or invoking this skill: 1) Do not run the 'npm install -g @laffy1309/emailcli' command unless you have verified the package source (npm page, repository, maintainer) and audited its code or trust the author. Global npm installs can execute arbitrary code. 2) Expect the CLI to access your mail accounts, attachments, and the filesystem (downloads/attachments). Run it in a controlled environment or sandbox if you need to test. 3) Confirm how you will authenticate provider accounts (OAuth flows, stored credentials) and whether those credentials are stored locally; the skill does not declare or manage secrets itself. 4) If you will allow the agent to invoke the skill autonomously, require explicit user confirmation for sending or deleting emails to avoid accidental data loss or exfiltration. 5) If you need a higher-assurance integration, prefer an official client or a vetted package/repository and inspect its source before granting access.

emailcli Skill

Use this skill whenever you need to interact with the user's email using the mail-cli command-line client.

Quick Reference

# Installation (if needed)
npm install -g @laffy1309/emailcli

# Commands
mail-cli list [--folder FOLDER] [--limit N] [--account EMAIL:PROVIDER]
mail-cli read <message-id> [--thread] [--download [dir]]
mail-cli search "<query>" [--account EMAIL:PROVIDER]
mail-cli send --to <addr> --subject "<subj>" --body "<text>" [--cc <addr>] [--bcc <addr>] [--attach <file>] [--save-draft] [--draft <id>]
mail-cli reply <message-id> --to <addr> [--cc <addr>]
mail-cli mark <message-id> --read|--unread
mail-cli mark --ids 1,2,3 --read|--unread  # Batch
mail-cli move <message-id> --folder "<folder>"
mail-cli move --ids 1,2,3 --folder "<folder>"  # Batch
mail-cli delete <message-id>
mail-cli delete --ids 1,2,3  # Batch
mail-cli folders [--account EMAIL:PROVIDER]
mail-cli status
mail-cli drafts --list|--delete <id>
mail-cli account list|add --provider gmail|outlook|remove --account EMAIL:PROVIDER|--all

Account Format

All accounts use email:provider format:

• Gmail: [e-mail]:gmail
• Outlook: [e-mail]:outlook

When multiple accounts exist, use --account EMAIL:PROVIDER to specify which one. If no account is specified, the CLI uses default:gmail internally.

JSON Output

All commands return JSON. Parse output programmatically:

Success:

{"ok": true}
{"id": "abc123", "from": "[e-mail]", "subject": "Hello", "date": "2024-01-01T00:00:00Z"}
[{"id": "1", "from": "[e-mail]"}, {"id": "2", "from": "[e-mail]"}]
{"id": "...", "saved": true}   // --save-draft output
{"removed": ["[e-mail]:gmail", "[e-mail]:outlook"]}  // account remove --all

Error:

{"error": {"code": "NO_ACCOUNTS", "message": "No accounts configured. Run 'mail-cli account add --provider gmail' first."}}
{"error": {"code": "DRAFT_NOT_FOUND", "message": "Draft with ID 'xxx' not found"}}
{"error": {"code": "MISSING_FLAG", "message": "Either --account <id> or --all is required"}}

Batch partial failure:

{"ok": true, "failed": [{"id": "2", "error": {"code": "NOT_FOUND", "message": "Email not found"}}]}

Command Patterns

Listing Emails

# Default: 20 most recent inbox emails
mail-cli list

# Specific folder (Gmail uses brackets)
mail-cli list --folder "[Gmail]/Sent"

# Limit results
mail-cli list --limit 50

# Specific account
mail-cli list --account [e-mail]:gmail

Reading Email

# Single email by ID (get ID from list output)
mail-cli read abc123

# Full thread
mail-cli read thread-456 --thread

# Read and download attachments to current directory
mail-cli read abc123 --download

# Read and download attachments to specific directory
mail-cli read abc123 --download ./attachments

Searching

# Gmail search syntax
mail-cli search "from:foo subject:bar has:attachment"

# Outlook KQL syntax
mail-cli search "from:foo subject:bar"

Sending Email

# Basic send
mail-cli send --to [e-mail] --subject "Hello" --body "Message"

# With CC/BCC
mail-cli send --to [e-mail] --cc [e-mail] --bcc [e-mail] --subject "Hello" --body "Message"

# From file
mail-cli send --to [e-mail] --subject "Hello" --body-file-path message.txt

# With attachment
mail-cli send --to [e-mail] --subject "Hello" --body "Message" --attach file.pdf

# Save as draft (don't send)
mail-cli send --to [e-mail] --subject "Hello" --body "Message" --save-draft

# Load and send existing draft
mail-cli send --draft draft-id-123 --subject "Updated Subject"

Replying

mail-cli reply <message-id> --to [e-mail]
mail-cli reply <message-id> --to [e-mail] --cc [e-mail]

Marking

# Single
mail-cli mark abc123 --read
mail-cli mark abc123 --unread

# Batch - comma-separated IDs (no spaces)
mail-cli mark --ids 1,2,3 --read

Moving

# Single
mail-cli move abc123 --folder "[Gmail]/Trash"

# Batch
mail-cli move --ids 1,2,3 --folder "[Gmail]/Archive"

Deleting

# Single (moves to trash)
mail-cli delete abc123

# Batch
mail-cli delete --ids 1,2,3

Folder Operations

# List all folders
mail-cli folders

# Mailbox status (message counts)
mail-cli status

Drafts

# List all saved drafts
mail-cli drafts --list

# Delete a draft by ID
mail-cli drafts --delete draft-id-123

Account Management

# Add account
mail-cli account add --provider gmail
mail-cli account add --provider outlook

# List accounts
mail-cli account list

# Remove specific account
mail-cli account remove --account [e-mail]:gmail

# Remove ALL accounts
mail-cli account remove --all

Workflows

Check Inbox

1. Run mail-cli list to get recent emails
2. Parse JSON output - each email has id, from, subject, date
3. Present summary to user
4. User can request specific email by ID

Send Email

1. Collect: recipient, subject, body (and optionally CC, attachments)
2. Compose command with proper escaping
3. Execute and check for {"ok": true} or error
4. Report success or error message

Save Draft

1. Compose the email without sending
2. Use --save-draft instead of sending
3. The output {"id": "...", "saved": true} contains the draft ID for later use

Load and Edit Draft

1. List drafts with mail-cli drafts --list
2. Load a draft with mail-cli send --draft <id>
3. Override any fields with command-line flags (CLI takes precedence over draft data)
4. Draft is automatically deleted after successful send

Search and Act

1. Run mail-cli search with appropriate query syntax
2. Present results
3. User can then mark, move, delete by ID

Batch Operations

1. Get list of IDs (from list or search results)
2. Use --ids 1,2,3 format (comma-separated, no spaces)
3. Check response for failed array to identify partial failures

Download Attachments

1. When reading an email, add --download or --download <dir>
2. Attachments are saved to the specified directory (or current directory)
3. Output includes downloads array with filename, path, and size for each attachment

Error Handling

If you receive an error response:

1. Extract error.code and error.message
2. Present the issue clearly to the user
3. Suggest remediation if applicable:
   • NO_ACCOUNTS: Run mail-cli account add --provider gmail|outlook
   • NOT_FOUND: The message ID doesn't exist or was already deleted
   • INVALID_CREDENTIALS: Re-authenticate with mail-cli account remove then mail-cli account add
   • DRAFT_NOT_FOUND: The draft ID doesn't exist or was already sent/deleted
   • MISSING_FLAG: Required flag missing (e.g., --account or --all for account remove)
   • CONFLICTING_FLAGS: Cannot use both --account and --all together

Important Notes

• Always use JSON output parsing - the CLI only outputs JSON
• Gmail folders use brackets: [Gmail]/Sent, [Gmail]/Trash, [Gmail]/Archive
• Message IDs from list/search are strings, preserve them exactly
• Batch IDs must be comma-separated with no spaces: --ids 1,2,3
• Reply requires both the message ID and --to with the recipient address
• Without --account, commands default to using the first available account
• Drafts are stored locally and persist across sessions
• --save-draft and --draft are mutually exclusive in the same command