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#

bash

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.

bash

# 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 Keywordsverification🔐Verification codes, activation验证码, OTP, activate, 绑定邮箱security⚠️Security alerts, login warnings安全提醒, security alert, 密码修改transactional📦Orders, payments, shipping订单确认, receipt, 发货通知promotion🎁Marketing, promotions, rewards奖励, 优惠, promo, discountsubscription📰Newsletters, digestsnewsletter, 订阅, weekly digestspam_like🚫Suspected spam中奖, FREE, click here nownormal—Regular email(default)

Trigger Keywords#

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

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

Common Commands#

bash

# 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):

json

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

Full configuration with all options (customize as needed):

json

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

Notification Options#

OptionDefaultDescriptioninclude_body``falseInclude email body preview in notificationsbody_max_length``500Max characters for body previewinclude_verification_codes``trueAuto-extract and show verification codesinclude_links``falseInclude action links (verify/reset)

Notifications#

When new emails arrive, the daemon sends formatted notifications:

text

📧 新邮件: 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/:

text

~/.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#

bash

# 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