IMAP/SMTP Email

Read, search, and manage email via IMAP. Send email via SMTP.

Supported Providers

Configuration

Setup

bash setup.sh

Config stored at ~/.config/imap-smtp-email/.env

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_MAILBOX=INBOX

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
[email protected]
SMTP_PASS=your_password
[email protected]

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

Multi-Account Support

Adding an Account

# Run setup and choose "Add a new account"
bash setup.sh

Or manually add prefixed variables:

# Work account (WORK_ prefix)
WORK_IMAP_HOST=imap.company.com
WORK_IMAP_PORT=993
[email protected]
WORK_IMAP_PASS=password
WORK_SMTP_HOST=smtp.company.com
WORK_SMTP_PORT=587
[email protected]
WORK_SMTP_PASS=password

Using a Named Account

# Use --account <name> before the command
node scripts/imap.js --account work check
node scripts/smtp.js --account work send --to [email protected] --subject Hi --body Hello

IMAP Commands (Receiving Email)

check — Check for New Emails

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

Options:

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

fetch — Fetch Full Email

node scripts/imap.js [--account <name>] fetch <uid> [--mailbox INBOX]

download — Download Attachments

node scripts/imap.js [--account <name>] download <uid> [--dir <path>] [--file <filename>]

search — Search Emails

node scripts/imap.js [--account <name>] search [options]

Options:

• --unseen: Only unread messages
• --seen: Only read messages
• --from <email>: From address contains
• --subject <text>: Subject contains
• --recent <time>: From last X time
• --since <date>: After date (YYYY-MM-DD)
• --before <date>: Before date (YYYY-MM-DD)
• --limit <n>: Max results (default: 20)

mark-read / mark-unread

node scripts/imap.js [--account <name>] mark-read <uid> [uid2 uid3...]
node scripts/imap.js [--account <name>] mark-unread <uid> [uid2 uid3...]

list-mailboxes

node scripts/imap.js [--account <name>] list-mailboxes

list-accounts

node scripts/imap.js list-accounts

SMTP Commands (Sending Email)

send — Send Email

node scripts/smtp.js [--account <name>] send --to <email> --subject <text> [options]

Required:

• --to: Recipient (comma-separated for multiple)
• --subject: Email subject

Optional:

• --body: Plain text body
• --html: Send body as HTML
• --body-file: Read body from file
• --html-file: Read HTML from file
• --cc: CC recipients
• --bcc: BCC recipients
• --attach: Attachments (comma-separated)
• --from: 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 "<h1>Welcome</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

node scripts/smtp.js [--account <name>] test

Important Notes

Gmail

• Regular password is rejected
• Must generate an App Password: https://myaccount.google.com/apppasswords
• Requires 2-Step Verification enabled

163.com / 126.com

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

Dependencies

npm install

Security Notes

• Config stored at ~/.config/imap-smtp-email/.env with 600 permissions
• File access whitelist limits where attachments can be saved
• Never commit .env files to version control