IMAP/SMTP Email Skill

Read and send email via IMAP/SMTP protocol. Works with any IMAP/SMTP server including Gmail, Outlook, 163.com, vip.163.com, 126.com, vip.126.com, 188.com, and vip.188.com.

Quick Setup

1. Create .env file with your credentials:

# IMAP Configuration (receiving email)
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=your@gmail.com
IMAP_PASS=your_app_password
IMAP_TLS=true
IMAP_MAILBOX=INBOX

# SMTP Configuration (sending email)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your@gmail.com
SMTP_PASS=your_app_password
SMTP_FROM=your@gmail.com

2. Install dependencies:

npm install

3. Test the connection:

node scripts/imap.js check
node scripts/smtp.js test

IMAP Commands (Receiving Email)

Check for new emails

node scripts/imap.js check --limit 10
node scripts/imap.js check --recent 2h        # Last 2 hours
node scripts/imap.js check --recent 30m       # Last 30 minutes

Fetch specific email

node scripts/imap.js fetch <uid>

Search emails

node scripts/imap.js search --unseen
node scripts/imap.js search --from "sender@example.com"
node scripts/imap.js search --subject "important"
node scripts/imap.js search --recent 24h

Mark as read/unread

node scripts/imap.js mark-read <uid>
node scripts/imap.js mark-unread <uid>

List mailboxes

node scripts/imap.js list-mailboxes

SMTP Commands (Sending Email)

Test SMTP connection

node scripts/smtp.js test

Send email

# 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"

Common Email Servers

Important for 163.com:

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

Configuration Options

IMAP:

• IMAP_HOST - Server hostname
• IMAP_PORT - Server port
• IMAP_USER - Your email address
• IMAP_PASS - Your password or app-specific password
• IMAP_TLS - Use TLS (true for SSL, false for STARTTLS)
• IMAP_REJECT_UNAUTHORIZED - Accept self-signed certs
• IMAP_MAILBOX - Default mailbox (INBOX)

SMTP:

• SMTP_HOST - Server hostname
• SMTP_PORT - Server port (587 for STARTTLS, 465 for SSL)
• SMTP_SECURE - true for SSL (465), false for STARTTLS (587)
• SMTP_USER - Your email address
• SMTP_PASS - Your password or app-specific password
• SMTP_FROM - Default sender email (optional)
• SMTP_REJECT_UNAUTHORIZED - Accept self-signed certs

Troubleshooting

Connection errors:

• Verify IMAP/SMTP server is running and accessible
• Check host/port settings in .env

Authentication failed:

• For Gmail: Use App Password (not account password if 2FA enabled)
• For 163.com: Use authorization code (授权码), not account password

TLS/SSL errors:

• For self-signed certs: Set IMAP_REJECT_UNAUTHORIZED=false or SMTP_REJECT_UNAUTHORIZED=false

Files

• SKILL.md - Skill documentation
• scripts/imap.js - IMAP CLI tool
• scripts/smtp.js - SMTP CLI tool
• package.json - Node.js dependencies
• .env - Your credentials (create manually)