zmail

What This Skill Does

zmail is an agent-centric email interface designed to move beyond the limitations of traditional web-based mail. By synchronizing IMAP mail into a local maildir-style structure and indexing content with SQLite (FTS5), it transforms your email into a queryable local database. Instead of a standard visual inbox, zmail prioritizes CLI-based searching, threading, and natural-language analysis. It acts as an "agent-first" bridge, allowing AI to treat your email as a persistent repository for communication artifacts like invoices, flight itineraries, and professional correspondence.

Installation

To install zmail, ensure you have Node.js 20+ installed on your system. Run the command npm install -g @cirne/zmail. The package includes a postinstall script that automatically builds the native better-sqlite3 binary. If the tool fails to launch, you may need to run npm rebuild better-sqlite3 using the same Node environment. Once installed, ensure your global npm bin directory is in your PATH. Configuration is handled via zmail setup, which will guide you through connecting your IMAP credentials and setting your OpenAI API key for intelligent querying.

Use Cases

• Automated Research: Have an agent scan your inbox for specific threads regarding "Project X" and summarize the last five email exchanges.
• Invoice Management: Automatically search for and extract metadata from purchase orders or utility bills stored in your email.
• Contextual Awareness: Enable an agent to cross-reference "who" a sender is based on communication history, utilizing enrichment features to provide context on new contacts.
• Quiet Productivity: Use natural language queries to retrieve information without the cognitive overhead of scrolling through a web-based UI.

Example Prompts

1. "zmail search --query 'invoice from AWS' --limit 3"
2. "zmail ask 'What is the status of the upcoming travel itinerary sent by Delta?'"
3. "zmail thread --id 1042 --summary"

Tips & Limitations

• Privacy Considerations: Features like zmail ask and zmail inbox transmit email content to OpenAI. Ensure you trust the service and are comfortable with the data privacy policy regarding your mail contents.
• Data Integrity: Your mail is stored locally in ~/.zmail. Be aware that zmail setup --clean --yes will permanently erase this data. Always maintain backups of important communications.
• Shell Security: Avoid passing raw, unsanitized text from emails directly into shell command strings to prevent potential command-injection vulnerabilities. Use structured arguments whenever possible.