mail-skill

Comprehensive email management skill. Use this skill when the user wants to fetch, search, read, send, reply to, move, delete, mark, or summarize emails. It...

Security Scan

The skill appears to do what it claims (local IMAP/SMTP email management with a local SQLite index), but it requires email account credentials and filesystem access which are not declared in registry metadata — review credentials, storage location, and agent file/network permissions before enabling.

Purpose & Capability

Name/description (mail management: fetch, search, read, send, summarize) align with included code. The client, DB, and CLI implement IMAP/SMTP fetching/sending, local SQLite indexing, attachment storage, search, and summarization flows described in SKILL.md.

Instruction Scope

SKILL.md instructs the agent to load a .env with email credentials, run the provided CLI, fetch emails to local storage, and summarize results — all within the stated purpose. It also directs the agent to save raw EMLs, JSON, and attachments locally and to read those files for summarization. This is expected for a local mail manager but grants the agent access to potentially sensitive mailbox contents and attachments.

Install Mechanism

No install spec; code is delivered directly in the skill bundle and depends on common Python packages (imap-tools, python-dotenv, beautifulsoup4, jinja2) listed in requirements.txt. No remote downloads or obscure install hosts are used.

Credentials

The skill requires mailbox credentials, IMAP/SMTP host and port, and writes/reads local mail storage (example.env documents these), but registry metadata declares no required env vars or primary credential. That mismatch is security-relevant: installing agents should expect to provide email passwords/app-specific passwords and permit the skill to read/write the mail_data directory. The number and sensitivity of these credentials is proportional to the functionality (email access), but the absence of declared required env vars in registry metadata reduces transparency.

Persistence & Privilege

always is false; the skill runs on demand and uses background processes/tasks that write to a local tasks directory and per-account mail_data. It does not request permanent platform-wide privileges or modify other skills. Background task files and local DB are normal for this functionality.

Assessment

What to consider before installing and using this skill: - Credentials: This skill needs your email address and password/app-specific password (IMAP/SMTP). Prefer creating and using an app-specific password or a dedicated mailbox account rather than your primary account. Do not paste credentials into a public place. - Local storage: The skill saves full raw emails (.eml), JSON, and attachments under mail_data (per-account directories). Ensure you are comfortable with those files residing on disk, and that the agent process has only the filesystem/network access you intend. - Registry metadata mismatch: The registry entry shows no required env vars, but the code and example.env clearly expect MAIL_ACCOUNT_* settings. Treat this as a transparency problem — the skill will read .env or environment variables to obtain credentials. - Agent permissions: The agent (or platform) may be able to read saved attachments and email text and could transmit them if given network/file permissions. Limit the agent's outbound/network permissions and consider running the skill in an isolated environment if you are concerned. - Code review: The provided Python code appears to use only IMAP/SMTP and local I/O (no external webhooks or remote upload). If you have the capability, review or run the code in a sandboxed environment first to confirm behavior. Pay attention to any logging or debug prints that might leak info. - Operational hygiene: Rotate credentials if you stop using the skill, restrict mailbox settings (enable app passwords, disable less-secure access), and securely delete mail_data when needed. If you need higher assurance, ask the skill publisher to update registry metadata to declare required env vars and clearly document storage paths, or run the skill against a throwaway mailbox first.

Mail Management Skill

This skill provides a robust command-line interface (scripts/mail_cli.py) for managing emails across multiple accounts.

Core Capabilities

• Fetch: Retrieve emails via IMAP and save them locally (.eml, .json, and SQLite index). Skips already downloaded emails based on message_id.
• Search: Query the local database for fast retrieval based on sender, subject, content, and date.
• Read: View the full content of an email, including its text and attachment metadata.
• Send/Reply/Forward: Send new emails or reply/forward existing ones via SMTP.
• Manage: Mark as read/starred, move between folders, or delete emails.
• Summarize: Since the skill provides full email text, you (Claude/Trae) can use your own intelligence to summarize the content, extract to-dos, or identify key dates.

Workflow

1. Initial Setup

The user must provide an .env file in the root directory (or use example.env as a template). Ensure python-dotenv, imap-tools, beautifulsoup4 are installed (pip install -r requirements.txt).

2. Fetching Emails

Fetching emails is an asynchronous process because it can take time. When you run the fetch command, it will return a task_id immediately.

./scripts/mail_cli.py fetch --limit 50 --days 7

Note: If you need to fetch more than 100 emails, you MUST append the --confirm flag, and you should ask the user for confirmation first.

Check the status of the fetch task using the returned task_id:

./scripts/mail_cli.py fetch-status "<task_id>"

Wait a few seconds and poll the status until it returns "status": "completed". Once completed, you MUST immediately use the summarize command to generate a professional report for the user, passing the task_id so it only summarizes the newly fetched emails:

./scripts/mail_cli.py summarize --task-id "<task_id>"

3. Summarizing Emails

Generate a professional, categorized Markdown report of emails (overall stats, verification codes, important emails, action required, and others):

./scripts/mail_cli.py summarize --task-id "<task_id>"

If you just want to summarize recent emails without a specific task:

./scripts/mail_cli.py summarize --limit 20

4. Searching Emails

Search locally first. This is much faster and doesn't hit the server:

./scripts/mail_cli.py search --query "meeting" --limit 10
./scripts/mail_cli.py search --sender "[e-mail]" --is-read 0

5. Reading an Email

To read the full text and get attachment info, use the message_id from the search results:

./scripts/mail_cli.py read "<message_id>"

6. Sending Emails

./scripts/mail_cli.py send --to "[e-mail]" --subject "Hello" --body "Message body" --attach "path/to/file1" "path/to/file2"

7. Managing Emails

• Mark: ./scripts/mail_cli.py mark "<message_id>" --read 1 --starred 1
• Move: ./scripts/mail_cli.py move "<message_id>" "Archive"
• Delete: ./scripts/mail_cli.py delete "<message_id>"

8. Exporting

Export local database for analysis:

./scripts/mail_cli.py export --format csv --output emails.csv

Best Practices

• Always Search Local First: Do not fetch unless the user explicitly asks to "check for new emails" or if a local search yields no results.
• Handling Replies: To reply, first read the original email to get context and sender, then use send with Re: <subject> and the recipient's address.
• Smart Summarization: Use the summarize command for quick professional reports. For deeper analysis of a single thread, use read and analyze the content directly.