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.
Important: Configuration is Pre-configured
The .env configuration file is automatically managed by WeSight Settings (邮箱设置). Do NOT ask the user to create or edit .env — just run the commands directly. If credentials are wrong, the scripts will return a clear error message; only then should you inform the user to check their email settings.
The .env file is located in this skill's directory (same folder as this SKILL.md file). The scripts load it automatically via an absolute path, regardless of the current working directory.
Configuration Reference
Create .env in the skill folder or set environment variables:
bash# IMAP Configuration (receiving email) IMAP_HOST=imap.gmail.com # Server hostname IMAP_PORT=993 # Server port IMAP_USER=your@email.com IMAP_PASS=your_password IMAP_TLS=true # Use TLS/SSL connection IMAP_REJECT_UNAUTHORIZED=true # Set to false for self-signed certs IMAP_MAILBOX=INBOX # Default mailbox # SMTP Configuration (sending email) SMTP_HOST=smtp.gmail.com # SMTP server hostname SMTP_PORT=587 # SMTP port (587 for STARTTLS, 465 for SSL) SMTP_SECURE=false # true for SSL (465), false for STARTTLS (587) SMTP_USER=your@gmail.com # Your email address SMTP_PASS=your_password # Your password or app password SMTP_FROM=your@gmail.com # Default sender email (optional) SMTP_REJECT_UNAUTHORIZED=true # Set to false for self-signed certs
Common Email Servers
| 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 |
| vip.126.com | imap.vip.126.com | 993 | smtp.vip.126.com | 465 |
| 188.com | imap.188.com | 993 | smtp.188.com | 465 |
| vip.188.com | imap.vip.188.com | 993 | smtp.vip.188.com | 465 |
| yeah.net | imap.yeah.net | 993 | smtp.yeah.net | 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 |
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.
bashnode scripts/imap.js check [--limit 10] [--mailbox INBOX] [--recent 2h]
Options:
--limit <n>: Max results (default: 10)--mailbox <name>: Mailbox to check (default: INBOX)--recent <time>: Only show emails from last X time (e.g., 30m, 2h, 7d)
fetch
Fetch full email content by UID.
bashnode scripts/imap.js fetch <uid> [--mailbox INBOX]
download
Download all attachments from an email, or a specific attachment.
bashnode scripts/imap.js download <uid> [--mailbox INBOX] [--dir <path>] [--file <filename>]
Options:
--mailbox <name>: Mailbox (default: INBOX)--dir <path>: Output directory (default: current directory)--file <filename>: Download only the specified attachment (default: download all)
search
Search emails with filters.
bashnode scripts/imap.js 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 (e.g., 30m, 2h, 7d) --since <date> After date (YYYY-MM-DD) --before <date> Before date (YYYY-MM-DD) --limit <n> Max results (default: 20) --mailbox <name> Mailbox to search (default: INBOX)
mark-read / mark-unread
Mark message(s) as read or unread.
bashnode scripts/imap.js mark-read <uid> [uid2 uid3...] node scripts/imap.js mark-unread <uid> [uid2 uid3...]
list-mailboxes
List all available mailboxes/folders.
bashnode scripts/imap.js list-mailboxes
SMTP Commands (Sending Email)
send
Send email via SMTP.
bashnode scripts/smtp.js send --to <email> --subject <text> [options]
Required:
--to <email>: Recipient (comma-separated for multiple)--subject <text>: Email subject, or--subject-file <file>
Optional:
--body <text>: Plain text body--html: Send body as HTML--body-file <file>: Read body from file--html-file <file>: Read HTML from file--cc <email>: CC recipients--bcc <email>: BCC recipients--attach <file>: Attachments (comma-separated)--from <email>: Override default sender
Examples:
bash# 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 by sending a test email to yourself.
bashnode scripts/smtp.js test
Dependencies
bashnpm install
Security Notes
- Store credentials in
.env(add to.gitignore) - For Gmail: use App Password if 2FA is enabled
- 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: use App Password if 2FA enabled
TLS/SSL errors:
- Match
IMAP_TLS/SMTP_SECUREsetting to server requirements - For self-signed certs: set
IMAP_REJECT_UNAUTHORIZED=falseorSMTP_REJECT_UNAUTHORIZED=false
