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:

CODEBLOCK0

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).

Config file format

CODEBLOCK1

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

CODEBLOCK2

Or manually add prefixed variables to ~/.config/imap-smtp-email/.env:

CODEBLOCK3

Using a named account

Add --account <name> before the command:

CODEBLOCK4

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)
• INLINECODE12 and ALLOWED_WRITE_DIRS are shared across all accounts (always unprefixed)

Common Email Servers

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 / INLINECODE15
• 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

CODEBLOCK5

Options:

• - --limit <n>: Max results (default: 10)
• INLINECODE17: Mailbox to check (default: INBOX)
• INLINECODE18: Only show emails from last X time (e.g., 30m, 2h, 7d)

fetch

CODEBLOCK6

download

CODEBLOCK7

Options:

• - --mailbox <name>: Mailbox (default: INBOX)
• INLINECODE20: Output directory (default: current directory)
• INLINECODE21: Download only the specified attachment (default: download all)

search

CODEBLOCK8

mark-read / mark-unread

CODEBLOCK9

list-mailboxes

CODEBLOCK10

list-accounts

CODEBLOCK11

Shows account name, email address, server addresses, and configuration status.

SMTP Commands (Sending Email)

send

CODEBLOCK12

Required:

• - --to <email>: Recipient (comma-separated for multiple)
• INLINECODE23: Email subject, or INLINECODE24

Optional:

• - --body <text>: Plain text body
• INLINECODE26: Send body as HTML
• INLINECODE27: Read body from file
• INLINECODE28: Read HTML from file
• INLINECODE29: CC recipients
• INLINECODE30: BCC recipients
• INLINECODE31: Attachments (comma-separated)
• INLINECODE32: Override default sender

Examples:
CODEBLOCK13

test

CODEBLOCK14

Dependencies

CODEBLOCK15

Security Notes

• - 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

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_SECURE setting to server requirements
• For self-signed certs: set IMAP_REJECT_UNAUTHORIZED=false or INLINECODE38