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
Create .env in the skill folder or set environment variables:
# 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_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 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.
```bash
node 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.
node scripts/imap.js fetch <uid> [--mailbox INBOX]
download
Download all attachments from an email, or a specific attachment.
node 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.
node 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.
node scripts/imap.js mark-read <uid> [uid2 uid3...]
node scripts/imap.js mark-unread <uid> [uid2 uid3...]
list-mailboxes
List all available mailboxes/folders.
node scripts/imap.js list-mailboxes
SMTP Commands (Sending Email)
send
Send email via SMTP.
node 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:
# 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.
node scripts/smtp.js test
Dependencies
npm install
Security Notes
- Store credentials in
.env(add to.gitignore) - Gmail: regular password is rejected — generate an App Password at https://myaccount.google.com/apppasswords
- For 163.com: use an authorization code (授权码, the Chinese interface label), rather than the 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_SECUREsetting to server requirements - For self-signed certs: set
IMAP_REJECT_UNAUTHORIZED=falseorSMTP_REJECT_UNAUTHORIZED=false