mail-skill

name	mail-skill
description	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 supports multiple accounts (IMAP/SMTP) and manages emails via a local SQLite index to avoid duplicate fetching and improve search performance.

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.