imap-email_skill

Overview

This skill reads and manages email via IMAP, supporting any standard IMAP server including ProtonMail Bridge and Gmail. It checks for new or unread messages, fetches full message content, searches mailboxes with flexible filters, and marks messages read or unread. The tool is designed for automation, cron integration, and simple CLI usage.

How this skill works

The skill connects to an IMAP server using credentials from a .env file or a setup helper. It exposes CLI commands to check mailboxes, fetch messages by UID, run advanced searches, list folders, and toggle read/unread flags. Outputs are JSON-friendly for easy parsing and integration with cron jobs or messaging delivery channels.

When to use it

• Automate periodic inbox checks and deliver summaries to a notification channel.
• Search for recent messages from a specific sender or containing keywords.
• Fetch full email content for archiving, processing, or downstream workflows.
• Integrate with ProtonMail Bridge or Gmail for app-password-based access.
• Mark processed messages read/unread as part of an automated pipeline.

Best practices

• Store IMAP credentials in a .env file and never commit it to version control.
• Use ProtonMail Bridge with its generated password and correct TLS settings.
• Prefer app-specific passwords for Gmail and enable IMAP in account settings.
• Match IMAP_TLS and port settings to the server (993 for SSL, 143 for STARTTLS).
• Limit search results and use recent/since filters to reduce load and false matches.

Example use cases

• Morning digest: run check --limit 10 --recent 12h, summarize unread items, and send a summary.
• Urgent monitor: run search --recent 1h --unseen and notify on messages containing priority keywords.
• Sender-specific scan: search --from "boss@example.com" --recent 24h, fetch content, then mark-read.
• Weekly archive: search --recent 7d --limit 50 and export full message bodies to backup storage.
• Mailbox discovery: list-mailboxes to validate folder names before running targeted searches.