IMAP/SMTP Email: Universal Email Control for AI Agents

With over 17,000 downloads, imap-smtp-email is ClawHub's most widely used email integration. Unlike API-based email skills that require provider-specific credentials and support only select services, this skill uses the standard IMAP and SMTP protocols — which means it works with any email provider that exposes these interfaces: Gmail, Outlook, 163.com, 126.com, 188.com, vip.163.com, QQ Mail, yeah.net, and any custom mail server.

The Problem It Solves

Most email integrations for AI agents are either too narrow (Gmail only, via OAuth) or too abstract (API wrappers that hide protocol details). For teams managing email in enterprise environments, using Chinese email providers, or running self-hosted mail servers, these options don't work.

IMAP and SMTP are the lowest-common-denominator protocols that every email server supports. By building on them directly, imap-smtp-email covers the entire email ecosystem — read any inbox, send from any account, download any attachment — without provider lock-in.

Architecture

The skill is two Node.js CLI scripts:

• imap.js — reads email via IMAP (check, fetch, search, download attachments, mark read/unread, list mailboxes)
• smtp.js — sends email via SMTP (plain text, HTML, attachments, CC, BCC)

Both use environment variables for credentials and output structured JSON, making them straightforward for Claude to parse and act on.

Setup

Provider Configuration

The skill includes a setup.sh wizard that interactively builds your .env file with pre-configured settings for 10 common providers. Or configure manually:

# IMAP (receiving)
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=you@gmail.com
IMAP_PASS=your_app_password
IMAP_TLS=true
IMAP_MAILBOX=INBOX
 
# SMTP (sending)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=you@gmail.com
SMTP_PASS=your_app_password
SMTP_FROM=you@gmail.com

Install dependencies:

npm install

Common Server Settings

163.com users: Use the authorization code (授权码), not your account password. Enable IMAP/SMTP in web settings first.

Gmail users: If 2FA is enabled, use an App Password — not your account password.

Reading Email (IMAP)

Check Recent Messages

# Last 10 emails in INBOX
node scripts/imap.js check --limit 10
 
# Emails from the last 2 hours
node scripts/imap.js check --recent 2h
 
# Only unread messages from last 30 minutes
node scripts/imap.js check --recent 30m --unseen

Time format: 30m (minutes), 2h (hours), 7d (days).

Response is a JSON array of message objects including uid, from, to, subject, date, body text/html, and flags.

Fetch a Specific Email

# Get full content by UID
node scripts/imap.js fetch 12345

Returns parsed email with headers, body (plain and HTML), and attachment metadata.

Search Emails

# All unread
node scripts/imap.js search --unseen
 
# From a specific sender
node scripts/imap.js search --from "boss@company.com"
 
# By subject
node scripts/imap.js search --subject "invoice"
 
# Date range
node scripts/imap.js search --since 2026-01-01 --before 2026-02-01
 
# Combined: unread invoices from last week
node scripts/imap.js search --unseen --subject "invoice" --recent 7d --limit 20

Search criteria are combined (AND logic). Results sorted newest-first.

Download Attachments

# Download all attachments from email UID 12345
node scripts/imap.js download 12345 --dir ./downloads
 
# Download a specific file only
node scripts/imap.js download 12345 --file report.pdf --dir ./downloads

If --file is specified and not found, the response lists available attachment filenames.

Manage Read Status

node scripts/imap.js mark-read 12345
node scripts/imap.js mark-unread 12345
 
# Multiple UIDs at once
node scripts/imap.js mark-read 12345 12346 12347

List Mailboxes

node scripts/imap.js list-mailboxes

Returns the full mailbox tree — useful for identifying folder names when searching outside INBOX (e.g., Sent, Spam, custom folders).

Sending Email (SMTP)

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 "Weekly Newsletter" \
  --html \
  --body "<h1>Updates</h1><p>Here's what happened this week...</p>"

Or from an HTML file:

node scripts/smtp.js send \
  --to recipient@example.com \
  --subject "Report" \
  --html-file report.html

Email with Attachment

node scripts/smtp.js send \
  --to client@example.com \
  --subject "Invoice #1234" \
  --body "Please find the invoice attached." \
  --attach invoice.pdf

Multiple attachments (comma-separated):

--attach "report.pdf,data.xlsx,screenshot.png"

Multiple Recipients with CC and BCC

node scripts/smtp.js send \
  --to "alice@company.com,bob@company.com" \
  --cc "manager@company.com" \
  --bcc "audit@company.com" \
  --subject "Quarterly Update" \
  --body "Please review the attached materials." \
  --attach q1-report.pdf

Test SMTP Connection

node scripts/smtp.js test

Sends a test email to yourself to verify the SMTP configuration before relying on it in production.

Practical Workflows

Monitor a Specific Sender

"Check if I have any unread emails from vendor@supplier.com in the last 24 hours"

Claude runs:

node scripts/imap.js search --from "vendor@supplier.com" --recent 24h --unseen

Process Incoming Invoices

"Find unread emails with 'invoice' in the subject, download any PDF attachments"

Claude runs search → gets UIDs → downloads attachments per UID → marks as read.

Batch Notification Sending

"Send the report.pdf to the 5 team members on this list"

Claude iterates the list and calls smtp.js send for each recipient.

imap-smtp-email vs. Provider-Specific Skills

How to Install

clawdbot install imap-smtp-email

Then run the setup wizard:

bash skillAssets/setup.sh

Or manually create .env with your IMAP and SMTP settings.

Practical Tips

1. Use app passwords, not account passwords. Gmail and most providers block standard password auth for IMAP/SMTP when 2FA is enabled. Generate an app-specific password from your account's security settings.

2. Start with smtp.js test. Before building any workflow, verify the SMTP connection sends successfully. Connection failures (wrong port, TLS mismatch) are much easier to debug on a test email than in the middle of a workflow.

3. Use --recent for monitoring workflows. When building a Claude workflow that checks email periodically, --recent 1h or --recent 30m is more reliable than tracking the last-checked timestamp yourself.

4. Download attachments to a specific directory. Use --dir /path/to/attachments consistently rather than the default current directory. It keeps downloaded files organized and makes them easier for Claude to reference in subsequent steps.

5. List mailboxes before searching non-INBOX folders. Folder names vary by provider. list-mailboxes reveals the exact names for Sent, Spam, Archive, and custom folders before you search them.

6. For 163.com and similar Chinese providers, authorization codes expire and must be renewed. If authentication fails after working previously, regenerate the authorization code in the web interface.

Considerations

• No event/push support: The skill polls via IMAP — it doesn't subscribe to server-push notifications. For real-time triggers, you'd need to run check on a schedule (cron or loop).
• Large inboxes can be slow: IMAP search performance depends on server implementation. Very large mailboxes may need --limit to keep response times reasonable.
• App passwords for Chinese providers: 163.com, 126.com, and similar providers use "authorization codes" rather than standard app passwords. The setup wizard guides you through this, but it's a common stumbling block.
• Attachment size limits: SMTP servers impose attachment size limits (typically 25MB for Gmail). Large files should be hosted externally and linked rather than attached.
• TLS configuration: Port 465 uses implicit SSL (SMTP_SECURE=true); port 587 uses STARTTLS (SMTP_SECURE=false). Mismatching these is a common configuration error.

The Bigger Picture

The imap-smtp-email skill represents a philosophy that's increasingly common in ClawHub's most downloaded tools: build on open standards, not proprietary APIs. By using IMAP and SMTP directly, it covers the entire email ecosystem without the per-provider integration work that API-based approaches require.

For teams operating in environments with Chinese email providers, enterprise mail servers, or simply a mix of email accounts that don't fit neatly into any one vendor's integration — this is the email skill that actually works.

View the skill on ClawHub: imap-smtp-email