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 configure your email account:

bash setup.sh

Configuration is stored at ~/.config/imap-smtp-email/.env (survives skill updates). If no config is found there, the skill falls back to a .env file in the skill directory (for backward compatibility).

Config file format

# Default account (no prefix)
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
[email protected]
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
[email protected]
SMTP_PASS=your_password
[email protected]
SMTP_REJECT_UNAUTHORIZED=true

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

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/imap-smtp-email/.env:

# Work account (WORK_ prefix)
WORK_IMAP_HOST=imap.company.com
WORK_IMAP_PORT=993
[email protected]
WORK_IMAP_PASS=password
WORK_IMAP_TLS=true
WORK_IMAP_REJECT_UNAUTHORIZED=true
WORK_IMAP_MAILBOX=INBOX
WORK_SMTP_HOST=smtp.company.com
WORK_SMTP_PORT=587
WORK_SMTP_SECURE=false
[email protected]
WORK_SMTP_PASS=password
[email protected]
WORK_SMTP_REJECT_UNAUTHORIZED=true

Using a named account

Add --account \x3Cname> before the command:

node scripts/imap.js --account work check
node scripts/smtp.js --account work send --to [email protected] --subject Hi --body Hello

Without --account, the default (unprefixed) account is used.

Account name rules

• Letters and digits only (e.g., work, 163, personal2)
• Case-insensitive: work and WORK refer to the same account
• The prefix in .env is always uppercase (e.g., WORK_IMAP_HOST)
• ALLOWED_READ_DIRS and ALLOWED_WRITE_DIRS are shared across all accounts (always unprefixed)

Common Email Servers

Important for Gmail:

• Gmail does not accept your regular account password
• You must generate an App Password: https://myaccount.google.com/apppasswords
• Use the generated 16-character App Password as IMAP_PASS / SMTP_PASS
• Requires Google Account with 2-Step Verification enabled

Important for 163.com:

• Use authorization code (授权码), not account password
• Enable IMAP/SMTP in web settings first

IMAP Commands (Receiving Email)

check

Check for new/unread emails.

node scripts/imap.js [--account \x3Cname>] check [--limit 10] [--mailbox INBOX] [--recent 2h]

Options:

• --limit \x3Cn>: Max results (default: 10)
• --mailbox \x3Cname>: Mailbox to check (default: INBOX)
• --recent \x3Ctime>: Only show emails from last X time (e.g., 30m, 2h, 7d)

fetch

Fetch full email content by UID.

node scripts/imap.js [--account \x3Cname>] fetch \x3Cuid> [--mailbox INBOX]

download

Download all attachments from an email, or a specific attachment.

node scripts/imap.js [--account \x3Cname>] download \x3Cuid> [--mailbox INBOX] [--dir \x3Cpath>] [--file \x3Cfilename>]

Options:

• --mailbox \x3Cname>: Mailbox (default: INBOX)
• --dir \x3Cpath>: Output directory (default: current directory)
• --file \x3Cfilename>: Download only the specified attachment (default: download all)

search

Search emails with filters.

node scripts/imap.js [--account \x3Cname>] search [options]

Options:
  --unseen           Only unread messages
  --seen             Only read messages
  --from \x3Cemail>     From address contains
  --subject \x3Ctext>   Subject contains
  --recent \x3Ctime>    From last X time (e.g., 30m, 2h, 7d)
  --since \x3Cdate>     After date (YYYY-MM-DD)
  --before \x3Cdate>    Before date (YYYY-MM-DD)
  --limit \x3Cn>        Max results (default: 20)
  --mailbox \x3Cname>   Mailbox to search (default: INBOX)

mark-read / mark-unread

Mark message(s) as read or unread.

node scripts/imap.js [--account \x3Cname>] mark-read \x3Cuid> [uid2 uid3...]
node scripts/imap.js [--account \x3Cname>] mark-unread \x3Cuid> [uid2 uid3...]

list-mailboxes

List all available mailboxes/folders.

node scripts/imap.js [--account \x3Cname>] list-mailboxes

list-accounts

List all configured email accounts.

node scripts/imap.js list-accounts
node scripts/smtp.js list-accounts

Shows account name, email address, server addresses, and configuration status.

SMTP Commands (Sending Email)

send

Send email via SMTP.

node scripts/smtp.js [--account \x3Cname>] send --to \x3Cemail> --subject \x3Ctext> [options]

Required:

• --to \x3Cemail>: Recipient (comma-separated for multiple)
• --subject \x3Ctext>: Email subject, or --subject-file \x3Cfile>

Optional:

• --body \x3Ctext>: Plain text body
• --html: Send body as HTML
• --body-file \x3Cfile>: Read body from file
• --html-file \x3Cfile>: Read HTML from file
• --cc \x3Cemail>: CC recipients
• --bcc \x3Cemail>: BCC recipients
• --attach \x3Cfile>: Attachments (comma-separated)
• --from \x3Cemail>: Override default sender

Examples:

# Simple text email
node scripts/smtp.js send --to [email protected] --subject "Hello" --body "World"

# HTML email
node scripts/smtp.js send --to [email protected] --subject "Newsletter" --html --body "\x3Ch1>Welcome\x3C/h1>"

# Email with attachment
node scripts/smtp.js send --to [email protected] --subject "Report" --body "Please find attached" --attach report.pdf

# Multiple recipients
node scripts/smtp.js send --to "[email protected],[email protected]" --cc "[email protected]" --subject "Update" --body "Team update"

test

Test SMTP connection by sending a test email to yourself.

node scripts/smtp.js [--account \x3Cname>] test

Dependencies

npm install

Security Notes

• Configuration is stored at ~/.config/imap-smtp-email/.env with 600 permissions (owner read/write only)
• Gmail: regular password is rejected — generate an App Password at https://myaccount.google.com/apppasswords
• For 163.com: use authorization code (授权码), not account password

Troubleshooting

Connection timeout:

• Verify server is running and accessible
• Check host/port configuration

Authentication failed:

• Verify username (usually full email address)
• Check password is correct
• For 163.com: use authorization code, not account password
• For Gmail: regular password won't work — generate an App Password at https://myaccount.google.com/apppasswords

TLS/SSL errors:

• Match IMAP_TLS/SMTP_SECURE setting to server requirements
• For self-signed certs: set IMAP_REJECT_UNAUTHORIZED=false or SMTP_REJECT_UNAUTHORIZED=false