{"skill":{"slug":"imap-smtp-email-maddy-fix","displayName":"IMAP/SMTP Email - Maddy Fix","summary":"Read and send email via IMAP/SMTP. Check for new/unread messages, fetch content, search mailboxes, mark as read/unread, and send emails with attachments. Sup...","description":"---\nname: imap-smtp-email\ndescription: Read and send email via IMAP/SMTP. Check for new/unread messages, fetch content, search mailboxes, mark as read/unread, and send emails with attachments. Supports multiple accounts. 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.\nmetadata:\n  openclaw:\n    emoji: \"📧\"\n    requires:\n      bins:\n        - node\n        - npm\n      env:\n        - IMAP_HOST\n        - IMAP_USER\n        - IMAP_PASS\n        - SMTP_HOST\n        - SMTP_USER\n        - SMTP_PASS\n    primaryEnv: SMTP_PASS\n---\n\n# IMAP/SMTP Email Tool\n\nRead, 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.\n\n## Configuration\n\nRun the setup script to install dependencies and configure your email account:\n\n```bash\nbash setup.sh\n```\n\nIf running commands manually without setup.sh, install dependencies first:\n\n```bash\nnpm install --production\n```\n\nConfiguration 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).\n\n### Config file format\n\n```bash\n# Default account (no prefix)\nIMAP_HOST=imap.gmail.com\nIMAP_PORT=993\nIMAP_USER=your@email.com\nIMAP_PASS=your_password\nIMAP_TLS=true\nIMAP_REJECT_UNAUTHORIZED=true\nIMAP_MAILBOX=INBOX\n\nSMTP_HOST=smtp.gmail.com\nSMTP_PORT=587\nSMTP_SECURE=false\nSMTP_USER=your@email.com\nSMTP_PASS=your_password\nSMTP_FROM=your@email.com\nSMTP_REJECT_UNAUTHORIZED=true\n\n# File access whitelist (security)\nALLOWED_READ_DIRS=~/Downloads,~/Documents\nALLOWED_WRITE_DIRS=~/Downloads\n```\n\n## Multi-Account\n\nYou can configure additional email accounts in the same config file. Each account uses a name prefix (uppercase) on all variables.\n\n### Adding an account\n\nRun the setup script and choose \"Add a new account\":\n\n```bash\nbash setup.sh\n```\n\nOr manually add prefixed variables to `~/.config/imap-smtp-email/.env`:\n\n```bash\n# Work account (WORK_ prefix)\nWORK_IMAP_HOST=imap.company.com\nWORK_IMAP_PORT=993\nWORK_IMAP_USER=me@company.com\nWORK_IMAP_PASS=password\nWORK_IMAP_TLS=true\nWORK_IMAP_REJECT_UNAUTHORIZED=true\nWORK_IMAP_MAILBOX=INBOX\nWORK_SMTP_HOST=smtp.company.com\nWORK_SMTP_PORT=587\nWORK_SMTP_SECURE=false\nWORK_SMTP_USER=me@company.com\nWORK_SMTP_PASS=password\nWORK_SMTP_FROM=me@company.com\nWORK_SMTP_REJECT_UNAUTHORIZED=true\n```\n\n### Using a named account\n\nAdd `--account <name>` before the command:\n\n```bash\nnode scripts/imap.js --account work check\nnode scripts/smtp.js --account work send --to foo@bar.com --subject Hi --body Hello\n```\n\nWithout `--account`, the default (unprefixed) account is used.\n\n### Account name rules\n\n- Letters and digits only (e.g., `work`, `163`, `personal2`)\n- Case-insensitive: `work` and `WORK` refer to the same account\n- The prefix in `.env` is always uppercase (e.g., `WORK_IMAP_HOST`)\n- `ALLOWED_READ_DIRS` and `ALLOWED_WRITE_DIRS` are shared across all accounts (always unprefixed)\n\n## Common Email Servers\n\n| Provider | IMAP Host | IMAP Port | SMTP Host | SMTP Port |\n|----------|-----------|-----------|-----------|-----------|\n| 163.com | imap.163.com | 993 | smtp.163.com | 465 |\n| vip.163.com | imap.vip.163.com | 993 | smtp.vip.163.com | 465 |\n| 126.com | imap.126.com | 993 | smtp.126.com | 465 |\n| vip.126.com | imap.vip.126.com | 993 | smtp.vip.126.com | 465 |\n| 188.com | imap.188.com | 993 | smtp.188.com | 465 |\n| vip.188.com | imap.vip.188.com | 993 | smtp.vip.188.com | 465 |\n| yeah.net | imap.yeah.net | 993 | smtp.yeah.net | 465 |\n| Gmail | imap.gmail.com | 993 | smtp.gmail.com | 587 |\n| Outlook | outlook.office365.com | 993 | smtp.office365.com | 587 |\n| QQ Mail | imap.qq.com | 993 | smtp.qq.com | 587 |\n| exmail.qq.com | imap.exmail.qq.com | 993 | smtp.exmail.qq.com | 465 |\n\n**Important for Gmail:**\n- Gmail does **not** accept your regular account password\n- You must generate an **App Password**: https://myaccount.google.com/apppasswords\n- Use the generated 16-character App Password as `IMAP_PASS` / `SMTP_PASS`\n- Requires Google Account with 2-Step Verification enabled\n\n**Important for 163.com:**\n- Use **authorization code** (授权码), not account password\n- Enable IMAP/SMTP in web settings first\n\n## IMAP Commands (Receiving Email)\n\n### check\nCheck for new/unread emails.\n\n```bash\nnode scripts/imap.js [--account <name>] check [--limit 10] [--mailbox INBOX] [--recent 2h]\n```\n\nOptions:\n- `--limit <n>`: Max results (default: 10)\n- `--mailbox <name>`: Mailbox to check (default: INBOX)\n- `--recent <time>`: Only show emails from last X time (e.g., 30m, 2h, 7d)\n\n### fetch\nFetch full email content by UID.\n\n```bash\nnode scripts/imap.js [--account <name>] fetch <uid> [--mailbox INBOX]\n```\n\n### download\nDownload all attachments from an email, or a specific attachment.\n\n```bash\nnode scripts/imap.js [--account <name>] download <uid> [--mailbox INBOX] [--dir <path>] [--file <filename>]\n```\n\nOptions:\n- `--mailbox <name>`: Mailbox (default: INBOX)\n- `--dir <path>`: Output directory (default: current directory)\n- `--file <filename>`: Download only the specified attachment (default: download all)\n\n### search\nSearch emails with filters.\n\n```bash\nnode scripts/imap.js [--account <name>] search [options]\n\nOptions:\n  --unseen           Only unread messages\n  --seen             Only read messages\n  --from <email>     From address contains\n  --subject <text>   Subject contains\n  --recent <time>    From last X time (e.g., 30m, 2h, 7d)\n  --since <date>     After date (YYYY-MM-DD)\n  --before <date>    Before date (YYYY-MM-DD)\n  --limit <n>        Max results (default: 20)\n  --mailbox <name>   Mailbox to search (default: INBOX)\n```\n\n### mark-read / mark-unread\nMark message(s) as read or unread.\n\n```bash\nnode scripts/imap.js [--account <name>] mark-read <uid> [uid2 uid3...]\nnode scripts/imap.js [--account <name>] mark-unread <uid> [uid2 uid3...]\n```\n\n### list-mailboxes\nList all available mailboxes/folders.\n\n```bash\nnode scripts/imap.js [--account <name>] list-mailboxes\n```\n\n### list-accounts\nList all configured email accounts.\n\n```bash\nnode scripts/imap.js list-accounts\nnode scripts/smtp.js list-accounts\n```\n\nShows account name, email address, server addresses, and configuration status.\n\n## SMTP Commands (Sending Email)\n\n### send\nSend email via SMTP.\n\n```bash\nnode scripts/smtp.js [--account <name>] send --to <email> --subject <text> [options]\n```\n\n**Required:**\n- `--to <email>`: Recipient (comma-separated for multiple)\n- `--subject <text>`: Email subject, or `--subject-file <file>`\n\n**Optional:**\n- `--body <text>`: Plain text body\n- `--html`: Send body as HTML\n- `--body-file <file>`: Read body from file\n- `--html-file <file>`: Read HTML from file\n- `--cc <email>`: CC recipients\n- `--bcc <email>`: BCC recipients\n- `--attach <file>`: Attachments (comma-separated)\n- `--from <email>`: Override default sender\n\n**Examples:**\n```bash\n# Simple text email\nnode scripts/smtp.js send --to recipient@example.com --subject \"Hello\" --body \"World\"\n\n# HTML email\nnode scripts/smtp.js send --to recipient@example.com --subject \"Newsletter\" --html --body \"<h1>Welcome</h1>\"\n\n# Email with attachment\nnode scripts/smtp.js send --to recipient@example.com --subject \"Report\" --body \"Please find attached\" --attach report.pdf\n\n# Multiple recipients\nnode scripts/smtp.js send --to \"a@example.com,b@example.com\" --cc \"c@example.com\" --subject \"Update\" --body \"Team update\"\n```\n\n### test\nTest SMTP connection by sending a test email to yourself.\n\n```bash\nnode scripts/smtp.js [--account <name>] test\n```\n\n## Security Notes\n\n- Configuration is stored at `~/.config/imap-smtp-email/.env` with `600` permissions (owner read/write only)\n- **Gmail**: regular password is rejected — generate an App Password at https://myaccount.google.com/apppasswords\n- For 163.com: use authorization code (授权码), not account password\n\n\n### Maddy / servers without IMAP ID\n\nSome valid IMAP servers, including Maddy, do not support the optional IMAP `ID` command. This fork catches synchronous `node-imap` `ID` errors and continues the connection instead of crashing.\n\n## Troubleshooting\n\n**Connection timeout:**\n- Verify server is running and accessible\n- Check host/port configuration\n\n**Authentication failed:**\n- Verify username (usually full email address)\n- Check password is correct\n- For 163.com: use authorization code, not account password\n- For Gmail: regular password won't work — generate an App Password at https://myaccount.google.com/apppasswords\n\n**TLS/SSL errors:**\n- Match `IMAP_TLS`/`SMTP_SECURE` setting to server requirements\n- For self-signed certs: set `IMAP_REJECT_UNAUTHORIZED=false` or `SMTP_REJECT_UNAUTHORIZED=false`\n","tags":{"latest":"0.0.14"},"stats":{"comments":0,"downloads":333,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1777575967844,"updatedAt":1778492814510},"latestVersion":{"version":"0.0.14","createdAt":1777575967844,"changelog":"Handle IMAP servers that do not support the optional ID command by catching synchronous node-imap errors and continuing the connection.","license":"MIT-0"},"metadata":{"setup":[{"key":"IMAP_HOST","required":true},{"key":"IMAP_USER","required":true},{"key":"IMAP_PASS","required":true},{"key":"SMTP_HOST","required":true},{"key":"SMTP_USER","required":true},{"key":"SMTP_PASS","required":true}],"os":null,"systems":null},"owner":{"handle":"troioi-vn","userId":"s17a2kkknw5n95dxnk0a36cred85jcns","displayName":"Athanasius","image":"https://avatars.githubusercontent.com/u/45875464?v=4"},"moderation":null}