back
loading skill details...
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...
---
name: imap-smtp-email
description: 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.
metadata:
openclaw:
emoji: "📧"
requires:
bins:
- node
- npm
---
# 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.
## Configuration
Run the setup script to configure your email account:
```bash
bash setup.sh
```
Configuration is split into two files:
- **`config.env`** (skill directory) — server hosts, ports, TLS settings, allowed dirs
- **`~/.openclaw/.env`** — credentials (user, password, from address)
Legacy fallback: `~/.config/imap-smtp-email/.env` (single combined file).
### Config file format
```bash
# Default account (no prefix)
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=your@email.com
IMAP_PASS=your_password
IMAP_TLS=true
IMAP_REJECT_UNAUTHORIZED=true
IMAP_MAILBOX=INBOX
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your@email.com
SMTP_PASS=your_password
SMTP_FROM=your@email.com
SMTP_REJECT_UNAUTHORIZED=true
# 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
bash setup.sh
```
Or manually add prefixed config to `config.env` and secrets to `~/.openclaw/.env`:
```bash
# Work account (WORK_ prefix)
WORK_IMAP_HOST=imap.company.com
WORK_IMAP_PORT=993
WORK_IMAP_USER=me@company.com
WORK_IMAP_PASS=password
WORK_IMAP_TLS=true
WORK_IMAP_REJECT_UNAUTHORIZED=true
WORK_IMAP_MAILBOX=INBOX
WORK_SMTP_HOST=smtp.company.com
WORK_SMTP_PORT=587
WORK_SMTP_SECURE=false
WORK_SMTP_USER=me@company.com
WORK_SMTP_PASS=password
WORK_SMTP_FROM=me@company.com
WORK_SMTP_REJECT_UNAUTHORIZED=true
```
### Using a named account
Add `--account <name>` before the command:
```bash
node scripts/imap.js --account work check
node scripts/smtp.js --account work send --to foo@bar.com --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
| 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 |
| Yahoo Mail | imap.mail.yahoo.com | 993 | smtp.mail.yahoo.com | 465 |
| 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 [--account <name>] 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.
```bash
node scripts/imap.js [--account <name>] fetch <uid> [--mailbox INBOX]
```
### download
Download all attachments from an email, or a specific attachment.
```bash
node scripts/imap.js [--account <name>] 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.
```bash
node scripts/imap.js [--account <name>] 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.
```bash
node scripts/imap.js [--account <name>] mark-read <uid> [uid2 uid3...]
node scripts/imap.js [--account <name>] mark-unread <uid> [uid2 uid3...]
```
### list-mailboxes
List all available mailboxes/folders.
```bash
node scripts/imap.js [--account <name>] list-mailboxes
```
### list-accounts
List all configured email accounts.
```bash
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)
### send
Send email via SMTP.
```bash
node scripts/smtp.js [--account <name>] 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.
```bash
node scripts/smtp.js [--account <name>] test
```
## Dependencies
```bash
npm install
```
## Security Notes
- Credentials are stored in `~/.openclaw/.env` with `600` permissions (owner read/write only). Connection config is in `config.env` in the skill directory
- **Gmail**: regular password is rejected — generate an App Password at https://myaccount.google.com/apppasswords
- 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: regular password won't work — generate an App Password at https://myaccount.google.com/apppasswords
- For Yahoo Mail: regular password won't work — generate an App Password at https://login.yahoo.com/account/security
**TLS/SSL errors:**
- Match `IMAP_TLS`/`SMTP_SECURE` setting to server requirements
- For self-signed certs: set `IMAP_REJECT_UNAUTHORIZED=false` or `SMTP_REJECT_UNAUTHORIZED=false`
don't have the plugin yet? install it then click "run inline in claude" again.
---
name: imap-smtp-email-fixed
description: 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.
metadata:
openclaw:
emoji: "📧"
requires:
bins:
- node
- npm
---
## intent
read, search, and manage incoming email via imap protocol. send outgoing email via smtp. supports gmail, outlook, 163.com, vip.163.com, 126.com, vip.126.com, 188.com, vip.188.com, yahoo, qq, and any standard imap/smtp server. use this skill when you need to check for new messages, fetch email content with attachments, search mailboxes by sender/subject/date, mark messages as read/unread, or send outbound email with optional attachments and cc/bcc. supports multiple configured email accounts.
## inputs
**environment setup (required before first use):**
- `config.env` (in skill directory): imap/smtp server hosts, ports, tls settings, file access whitelist
- `~/.openclaw/.env` (user home): email credentials (user, password, from address). set permissions to 600 (owner read/write only)
- legacy fallback: `~/.config/imap-smtp-email/.env` (single combined file, if openclaw dir not present)
**system requirements:**
- node.js and npm installed
- network access to configured imap/smtp servers
- for gmail: app password from https://myaccount.google.com/apppasswords (regular account password rejected)
- for 163.com: authorization code (授权码) enabled in web settings, not account password
**account configuration options:**
- default account: unprefixed variables (e.g., `IMAP_HOST`, `SMTP_HOST`)
- named accounts: uppercase prefix on all variables (e.g., `WORK_IMAP_HOST`, `WORK_SMTP_HOST`)
- use `--account <name>` flag to select account at runtime (case-insensitive, letters/digits only)
- `ALLOWED_READ_DIRS` and `ALLOWED_WRITE_DIRS` shared across all accounts (unprefixed, comma-separated paths with `~` expansion)
**common server endpoints:**
| 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 |
| yahoo mail | imap.mail.yahoo.com | 993 | smtp.mail.yahoo.com | 465 |
| outlook | outlook.office365.com | 993 | smtp.office365.com | 587 |
| qq mail | imap.qq.com | 993 | smtp.qq.com | 587 |
## procedure
**setup (one-time):**
1. run interactive setup script to configure accounts
- input: none (script prompts for account name, email, server details, credentials)
- output: `config.env` populated with server settings, `~/.openclaw/.env` populated with credentials
- execution: `bash setup.sh`
alternatively, manually configure:
2. create or edit `config.env` in skill directory with server hosts, ports, tls/ssl flags, and file access whitelist
- input: text editor
- output: config.env file with format shown below
- execution: `nano config.env` or equivalent
3. create or edit `~/.openclaw/.env` with email credentials
- input: text editor, credential values
- output: ~/.openclaw/.env with 600 permissions (owner read/write only)
- execution: `nano ~/.openclaw/.env && chmod 600 ~/.openclaw/.env`
**receive email (imap):**
4. check mailbox for new/unread messages
- input: account name (optional, default unprefixed), mailbox name, result limit, time filter
- output: json array of message headers with uid, from, subject, date, flags
- execution: `node scripts/imap.js [--account <name>] check [--limit 10] [--mailbox INBOX] [--recent 2h]`
5. fetch full email content including body and headers by uid
- input: account name (optional), uid (required), mailbox name (optional)
- output: json object with full email content (plain text and/or html), headers, sender, recipients
- execution: `node scripts/imap.js [--account <name>] fetch <uid> [--mailbox INBOX]`
6. list all available mailboxes/folders for the account
- input: account name (optional)
- output: json array of mailbox names and hierarchy (nested structure if supported by server)
- execution: `node scripts/imap.js [--account <name>] list-mailboxes`
7. search mailbox by multiple filters (sender, subject, date range, read status)
- input: account name (optional), search filters (unseen/seen flag, from address, subject text, date range, time filter, result limit), mailbox name
- output: json array of matching message headers with uid, from, subject, date, flags
- execution: `node scripts/imap.js [--account <name>] search [--unseen] [--from <email>] [--subject <text>] [--since YYYY-MM-DD] [--before YYYY-MM-DD] [--recent 30m|2h|7d] [--limit 20] [--mailbox INBOX]`
8. mark one or more messages as read
- input: account name (optional), uid(s) (required, space-separated), mailbox name (optional)
- output: json object with status and count of messages marked
- execution: `node scripts/imap.js [--account <name>] mark-read <uid> [uid2 uid3...]`
9. mark one or more messages as unread
- input: account name (optional), uid(s) (required, space-separated), mailbox name (optional)
- output: json object with status and count of messages marked
- execution: `node scripts/imap.js [--account <name>] mark-unread <uid> [uid2 uid3...]`
10. download attachments from email by uid
- input: account name (optional), uid (required), mailbox name (optional), output directory path (must be in ALLOWED_WRITE_DIRS), optional specific filename to filter
- output: attachments written to specified directory, json object with list of saved files and paths
- execution: `node scripts/imap.js [--account <name>] download <uid> [--mailbox INBOX] [--dir ~/Downloads] [--file <filename>]`
**send email (smtp):**
11. send email with optional html, attachments, cc, bcc
- input: account name (optional), to address(es) (required, comma-separated), subject text or subject-file path (required), body text or html or body-file or html-file (optional), cc address(es) (optional), bcc address(es) (optional), attachments (optional, comma-separated file paths, must be in ALLOWED_READ_DIRS), from override (optional)
- output: json object with smtp status code, message id, and confirmation timestamp
- execution: `node scripts/smtp.js [--account <name>] send --to <email> --subject <text> [--body <text>] [--html] [--body-file <file>] [--html-file <file>] [--cc <email>] [--bcc <email>] [--attach <file>] [--from <email>]`
12. test smtp connection by sending test email to configured from address
- input: account name (optional)
- output: json object with connection status, smtp response code, and test email confirmation
- execution: `node scripts/smtp.js [--account <name>] test`
**account management:**
13. list all configured email accounts
- input: none
- output: json array with account names, email addresses, server hosts, configuration status
- execution: `node scripts/imap.js list-accounts` or `node scripts/smtp.js list-accounts`
## decision points
**authentication method by provider:**
- if provider is gmail: use app password from https://myaccount.google.com/apppasswords (regular account password will fail with "authentication failed" error). require google account with 2-step verification enabled.
- else if provider is 163.com or vip.163.com: use authorization code (授权码) from web settings, not account password. enable imap/smtp in web settings first.
- else if provider is yahoo mail: use app password from https://login.yahoo.com/account/security (regular password rejected).
- else: use account password directly.
**account selection:**
- if `--account <name>` flag provided on command line: use named account with uppercase prefix (e.g., `WORK_IMAP_HOST`).
- else: use default (unprefixed) account (e.g., `IMAP_HOST`).
**tls/ssl configuration:**
- if port is 465 (common for smtp): set `SMTP_SECURE=true`.
- else if port is 587 (common for smtp): set `SMTP_SECURE=false` (starttls mode).
- if port is 993 (common for imap): set `IMAP_T