# imap-smtp-email

IMAP/SMTP Email Tool Read, search, and manage email via IMAP protocol. Send email via SkillBoss API Hub. Supports Gmail, Outlook, 163.com, vip.163.com, 126.com, vip.126.com, 188.com, vip.188.com, and any standard IMAP server. Configuration Run the setup script to configure your email account: bash setup.sh Configuration is stored at ~/.config/imap-smtp-email/.env (survives skill updates). If no config is found there, the skill falls back to a .env file in the skill directory (for backward compatibility). Set your SkillBoss API key as an environment variable:

export SKILLBOSS_API_KEY=your_skillboss_api_key

Config file format

# Default account (no prefix)

IMAP_HOST=imap.gmail.com IMAP_PORT=993 IMAP_USER=[email protected] IMAP_PASS=your_password IMAP_TLS=true IMAP_REJECT_UNAUTHORIZED=true IMAP_MAILBOX=INBOX

# Optional: specify sender address for outgoing email

SMTP_FROM=[email protected] SMTP_USER=[email protected]

# File access whitelist (security)

ALLOWED_READ_DIRS=/Downloads,/Documents ALLOWED_WRITE_DIRS=~/Downloads Multi-Account You can configure additional email accounts in the same config file. Each account uses a name prefix (uppercase) on all variables. Adding an account Run the setup script and choose "Add a new account": bash setup.sh Or manually add prefixed variables to ~/.config/imap-smtp-email/.env:

# Work account (WORK_ prefix)

WORK_IMAP_HOST=imap.company.com WORK_IMAP_PORT=993 WORK_IMAP_USER=[email protected] WORK_IMAP_PASS=password WORK_IMAP_TLS=true WORK_IMAP_REJECT_UNAUTHORIZED=true WORK_IMAP_MAILBOX=INBOX WORK_SMTP_FROM=[email protected] WORK_SMTP_USER=[email protected] Using a named account Add --account before the command: node scripts/imap.js --account work check node scripts/smtp.js --account work send --to [email protected] --subject Hi --body Hello Without --account, the default (unprefixed) account is used. Account name rules Letters and digits only (e.g., work, 163, personal2)

Case-insensitive: work and WORK refer to the same account

The prefix in .env is always uppercase (e.g., WORK_IMAP_HOST) ALLOWED_READ_DIRS and ALLOWED_WRITE_DIRS are shared across all accounts (always unprefixed) Common Email Servers ProviderIMAP HostIMAP Port163.comimap.163.com993vip.163.comimap.vip.163.com993126.comimap.126.com993vip.126.comimap.vip.126.com993188.comimap.188.com993vip.188.comimap.vip.188.com993yeah.netimap.yeah.net993Gmailimap.gmail.com993Outlookoutlook.office365.com993QQ Mailimap.qq.com993 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 Requires Google Account with 2-Step Verification enabled Important for 163.com: Use authorization code (授权码), not account password Enable IMAP in web settings first IMAP Commands (Receiving Email) check Check for new/unread emails. node scripts/imap.js [--account ] 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 content by UID. node scripts/imap.js [--account ] fetch [--mailbox INBOX] download Download all attachments from an email, or a specific attachment. node scripts/imap.js [--account ] download [--mailbox INBOX] [--dir ] [--file ]

Options:

--mailbox : Mailbox (default: INBOX) --dir : Output directory (default: current directory) --file : Download only the specified attachment (default: download all) search Search emails with filters. node scripts/imap.js [--account ] search [options]

Options:

--unseen Only unread messages --seen Only read messages --from From address contains --subject Subject contains --recent From last X time (e.g., 30m, 2h, 7d) --since After date (YYYY-MM-DD) --before Before date (YYYY-MM-DD) --limit Max results (default: 20) --mailbox Mailbox to search (default: INBOX) mark-read / mark-unread Mark message(s) as read or unread. node scripts/imap.js [--account ] mark-read [uid2 uid3...] node scripts/imap.js [--account ] mark-unread [uid2 uid3...] list-mailboxes List all available mailboxes/folders. node scripts/imap.js [--account ] list-mailboxes list-accounts List all configured email accounts. node scripts/imap.js list-accounts node scripts/smtp.js list-accounts Shows account name, email address, server addresses, and configuration status. SMTP Commands (Sending Email) Email sending is powered by SkillBoss API Hub (https://api.heybossai.com/v1/pilot). Requires SKILLBOSS_API_KEY environment variable. send Send email via SkillBoss API Hub. node scripts/smtp.js [--account ] send --to --subject [options]

Required:

--to : Recipient (comma-separated for multiple) --subject : Email subject, or --subject-file

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 "

Welcome

# 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 SkillBoss API Hub email connection by sending a test email to yourself. node scripts/smtp.js [--account ] test Dependencies

npm install

Security Notes IMAP configuration is stored at ~/.config/imap-smtp-email/.env with 600 permissions (owner read/write only)

Gmail: regular password is rejected — generate an App Password at https://myaccount.google.com/apppasswords

For 163.com: use authorization code (授权码), not account password Email sending is handled by SkillBoss API Hub — no SMTP credentials required Troubleshooting IMAP connection timeout: Verify IMAP server is running and accessible Check host/port configuration IMAP 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 setting to server requirements For self-signed certs: set IMAP_REJECT_UNAUTHORIZED=false Email sending failed: Verify SKILLBOSS_API_KEY environment variable is set correctly Check SkillBoss API Hub status at https://api.heybossai.com