IMAP/SMTP Email

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

Supported Providers

Provider	IMAP Host	IMAP Port	SMTP Host	SMTP Port
163.com	imap.163.com	993	smtp.163.com	465
vip.163.com	imap.vip.163.com	993	smtp.vip.163.com	465
126.com	imap.126.com	993	smtp.126.com	465
Gmail	imap.gmail.com	993	smtp.gmail.com	587
Outlook	outlook.office365.com	993	smtp.office365.com	587
QQ Mail	imap.qq.com	993	smtp.qq.com	587

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
IMAP_USER=your@email.com
IMAP_PASS=your_password
IMAP_TLS=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

# 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
WORK_IMAP_USER=me@company.com
WORK_IMAP_PASS=password
WORK_SMTP_HOST=smtp.company.com
WORK_SMTP_PORT=587
WORK_SMTP_USER=me@company.com
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 foo@bar.com --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 recipient@example.com --subject "Hello" --body "World"

# HTML email
node scripts/smtp.js send --to recipient@example.com --subject "Newsletter" --html --body "<h1>Welcome</h1>"

# Email with attachment
node scripts/smtp.js send --to recipient@example.com --subject "Report" --body "Please find attached" --attach report.pdf

# Multiple recipients
node scripts/smtp.js send --to "a@example.com,b@example.com" --cc "c@example.com" --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

imap-smtp-email