IMAP/SMTP Email Tool

Read, search, and manage email via IMAP protocol. Send email via SMTP. Supports Gmail, Outlook, 163.com, vip.163.com, 126.com, vip.126.com, 188.com, vip.188.com, and any standard IMAP/SMTP server.

Configuration

Run the setup script to install dependencies and configure your email account:

bash setup.sh

If running commands manually without setup.sh, install dependencies first:

npm install --production

Configuration is stored at ~/.config/mail-skills/.env (shared with caldav-sync skill, survives skill updates). If no shared config is found, the skill checks ~/.config/imap-smtp-email/.env (legacy) and then a .env file in the skill directory.

Config file format (shared)

# Default account
PROVIDER=163
USERNAME=your@163.com
PASSWORD=your_password

# File access whitelist (security)
ALLOWED_READ_DIRS=~/Downloads,~/Documents
ALLOWED_WRITE_DIRS=~/Downloads

The PROVIDER preset auto-fills IMAP/SMTP server settings. For custom servers:

PROVIDER=custom
USERNAME=your@email.com
PASSWORD=your_password
IMAP_HOST=imap.example.com
SMTP_HOST=smtp.example.com

Legacy config file format

If you have an existing ~/.config/imap-smtp-email/.env, it takes priority over the shared config. The format is:

# Default account (no prefix)
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=your@email.com
IMAP_PASS=your_password
IMAP_TLS=true
IMAP_REJECT_UNAUTHORIZED=true
IMAP_MAILBOX=INBOX

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your@email.com
SMTP_PASS=your_password
SMTP_FROM=your@email.com
SMTP_REJECT_UNAUTHORIZED=true

# File access whitelist (security)
ALLOWED_READ_DIRS=~/Downloads,~/Documents
ALLOWED_WRITE_DIRS=~/Downloads

Run bash setup.sh to migrate your legacy config to the shared format.

Multi-Account

You can configure additional email accounts in the same config file. Each account uses a name prefix (uppercase) on all variables.

Adding an account

Run the setup script and choose "Add a new account":

bash setup.sh

Or manually add prefixed variables to ~/.config/mail-skills/.env:

# Work account (WORK_ prefix)
WORK_PROVIDER=gmail
WORK_USERNAME=me@company.com
WORK_PASSWORD=app_password