ClawHub

Email Bridge

Other

Email management skill for AI assistants with real-time notifications, smart categorization (7 categories), verification code extraction, and HTML content sanitization. Supports Gmail, QQ Mail, and NetEase.

Install

openclaw skills install email-bridge

Email Bridge Skill

Email management skill for OpenClaw. Provides real-time email monitoring with smart categorization and clean notifications for AI assistants.

Features

  • Real-time notifications: IMAP IDLE (QQ/NetEase) + polling (Gmail)
  • Smart categorization: 7 categories with subject-only classification
  • Verification code extraction: Context-aware, low false positive rate
  • HTML content sanitization: Clean text from HTML emails, remove invisible chars
  • Prompt injection protection: Safe email content for AI processing
  • Multi-provider support: Gmail (API), QQ Mail (IMAP), NetEase (IMAP)

Installation

cd skills/email-bridge
pip install -e .

Setup (Manual CLI Required)

⚠️ Security Note: Do NOT share authorization codes in chat. Configure accounts via CLI only.

# Add account (prompts for authorization code securely)
email-bridge accounts add your@qq.com -p qq

# Sync emails
email-bridge sync

# Start daemon for real-time notifications
email-bridge daemon start -d

Getting Authorization Codes

QQ Mail: https://service.mail.qq.com/detail/0/75 (send SMS, get 16-char code)

NetEase (163/126): Settings → POP3/SMTP/IMAP → Enable → Get code

Gmail: Requires OAuth setup (see README.md)

Capabilities

  • Receive emails: Sync and read emails from configured accounts
  • Send emails: Send emails via SMTP
  • Real-time notifications: Push to OpenClaw via openclaw system event
  • Smart categorization: 7 categories with keyword-based classification
  • Verification code extraction: Context-aware extraction with low false positives
  • Link extraction: Extract action links from emails
  • HTML sanitization: Clean text extraction with invisible char removal
  • Prompt injection protection: Sanitize email content for safe AI processing

Email Categories

Subject-only classification for fast, reliable categorization:

CategoryIconDescriptionExample Keywords
verification🔐Verification codes, activation验证码, OTP, activate, 绑定邮箱
security⚠️Security alerts, login warnings安全提醒, security alert, 密码修改
transactional📦Orders, payments, shipping订单确认, receipt, 发货通知
promotion🎁Marketing, promotions, rewards奖励, 优惠, promo, discount
subscription📰Newsletters, digestsnewsletter, 订阅, weekly digest
spam_like🚫Suspected spam中奖, FREE, click here now
normal—Regular email(default)

Trigger Keywords

Chinese: 邮箱、邮件、发邮件、查看邮件、验证码、QQ邮箱、Gmail

English: email, mail, send email, check email, verification code

Common Commands

# List recent emails
email-bridge messages list -n 10

# Get verification codes from recent emails
email-bridge codes

# Send email
email-bridge send -a <account_id> -t recipient@example.com -s "Subject" -b "Body"

# Daemon management
email-bridge daemon status
email-bridge daemon stop

Configuration

Configuration file: ~/.email-bridge/config.json

Default configuration (auto-generated, minimal):

{
  "daemon": {
    "poll_interval": 300,
    "notify_openclaw": true
  }
}

Full configuration with all options (customize as needed):

{
  "daemon": {
    "poll_interval": 300,
    "notify_openclaw": true,
    "notification": {
      "include_body": false,
      "body_max_length": 500,
      "include_verification_codes": true,
      "include_links": false
    }
  }
}

Notification Options

OptionDefaultDescription
include_bodyfalseInclude email body preview in notifications
body_max_length500Max characters for body preview
include_verification_codestrueAuto-extract and show verification codes
include_linksfalseInclude action links (verify/reset)

Notifications

When new emails arrive, the daemon sends formatted notifications:

📧 新邮件: account@qq.com

1. 🔐 Google
   您的验证码
   ✨ 验证码: 123456

2. ⚠️ Microsoft
   登录提醒
   📝 We noticed a new sign-in...

3. 🎁 OKX
   150 USDT 奖励等您拿
   📝 亲爱的欧易用户，欧易诚邀您加入邀请好友计划...

HTML Content Processing

HTML-only emails are processed through:

  1. Tag stripping: Remove <style>, <script>, and all HTML tags
  2. Entity decoding: Convert HTML entities to text
  3. Invisible char removal: Remove zero-width spaces, BOM, etc.
  4. Whitespace normalization: Clean up spacing
  5. Prompt injection protection: Remove dangerous patterns

Example: HTML with invisible chars → Clean readable text

Security Features

  • Subject-only classification: No body scanning for privacy
  • Context-aware code extraction: Only extract near verification keywords
  • Invisible char sanitization: Remove U+200B, U+FEFF, U+034F, etc.
  • Prompt injection protection: Filter dangerous instruction patterns
  • Address pattern exclusion: Don't extract numbers from addresses

Data Storage

All data stored locally at ~/.email-bridge/:

~/.email-bridge/
├── email_bridge.db    # SQLite database (accounts, messages)
├── config.json        # Configuration file
├── daemon.pid         # Daemon process ID
├── daemon.log         # Logs
└── gmail/
    ├── credentials.json  # OAuth credentials
    └── token_*.json      # OAuth tokens

⚠️ Credentials are stored unencrypted. Protect this directory.

Revoking Access

# Stop daemon
email-bridge daemon stop

# Remove all stored data
rm -rf ~/.email-bridge

# For Gmail: revoke at https://myaccount.google.com/permissions
# For QQ/NetEase: regenerate authorization codes in email settings

Dependencies

All from PyPI:

  • click >= 8.0
  • pydantic >= 2.0
  • imaplib2 >= 3.6
  • google-api-python-client >= 2.0 (Gmail only)
  • google-auth-oauthlib >= 1.0 (Gmail only)

Security Notes

  1. Never share authorization codes in chat - use CLI interactively
  2. Credentials stored unencrypted - protect ~/.email-bridge/ directory
  3. Email content is sanitized - prompt injection protection enabled
  4. Daemon runs with user privileges - no elevated access needed
  5. Subject-only classification - privacy-conscious processing

Changelog

v0.6.2

  • Add PROMOTION category for marketing emails (🎁 icon)
  • Add TRANSACTIONAL category for orders/shipping (📦 icon)
  • Expand keyword pools for all categories
  • Add invisible character sanitization (U+200B, U+FEFF, U+034F, etc.)
  • Improve HTML-to-text extraction
  • Update documentation (DESIGN.md, README.md)

v0.6.1

  • Add IDLE keepalive (60s timeout) for connection stability
  • Add sync retry mechanism (up to 3 retries)
  • Improve daemon reliability for flaky networks

v0.6.0

  • Smart notification format based on email category
  • Prompt injection protection with sanitize_for_notification()
  • HTML-to-text fallback for HTML-only emails
  • Subject-only classification for privacy
  • Context-aware verification code extraction
  • Category icons (🔐 ⚠️ 📦 🎁 📰 🚫)

v0.5.7

  • Initial ClawHub release
  • Gmail, QQ Mail, NetEase support
  • IMAP IDLE real-time notifications
  • Verification code extraction
  • Link extraction