Zoho Email Integration for Clawdbot

v2.2.9 - Complete Zoho Mail integration with OAuth2, REST API backend (5-10x faster), Clawdbot extension with /email commands, and advanced email automation features. Perfect for email workflows, monitoring, and bulk operations in your Clawdbot projects.

🔒 Security Notice (v2.2.0)

SECURITY UPDATE: This version fixes critical vulnerabilities identified in security audit. Upgrade recommended for all users.

Fixed vulnerabilities:

✅ CRITICAL: Command injection in JavaScript handler
✅ HIGH: Metadata mismatch (credential requirements)
✅ MEDIUM: Insufficient input validation
✅ LOW: Token file permission enforcement

See SECURITY.md for details and migration guide.

🚀 Quick Start (recommended path)

# 1) Install
clawhub install zoho-email-integration
cd zoho-email-integration  # (or wherever ClawHub installed it)
 
# 2) Install Python deps (needed for REST API mode)
pip3 install -r requirements.txt
 
# 3) Set your mailbox (required for both OAuth + app-password modes)
export ZOHO_EMAIL="your-email@domain.com"
 
# 4) OAuth2 setup (recommended: enables REST API + auto token refresh)
python3 scripts/oauth-setup.py
 
# 5) Sanity-check everything
python3 scripts/zoho-email.py doctor
 
# 6) Test
python3 scripts/zoho-email.py unread

Quick Start (app-password mode)

If you don't want OAuth2 yet:

export ZOHO_EMAIL="your-email@domain.com"
export ZOHO_PASSWORD="your-app-specific-password"
python3 scripts/zoho-email.py doctor
python3 scripts/zoho-email.py unread --api-mode imap

OAuth token location (default): ~/.clawdbot/zoho-mail-tokens.json

✨ Features

Core Features

✅ OAuth2 Authentication - Secure authentication with automatic token refresh ✅ REST API Backend - 5-10x faster than IMAP/SMTP (auto-enabled with OAuth2) ✅ Read & Search - Search emails with advanced filters ✅ Send Emails - Plain text, HTML, CC/BCC support ✅ Attachments - Send and download attachments ✅ HTML Emails - Send rich-formatted emails with templates ✅ Batch Operations - Mark, delete, move multiple emails efficiently ✅ Folder Management - Access all folders (Inbox, Sent, Drafts, etc.)

Performance

⚡ 5-10x faster operations with REST API mode ⚡ Connection pooling for persistent HTTP connections ⚡ Server-side filtering reduces data transfer ⚡ Automatic fallback to IMAP if REST API unavailable

📚 Documentation

SKILL.md - Complete guide with examples
OAUTH2_SETUP.md - OAuth2 setup instructions
SECURITY.md - Security best practices and audit results
CHANGELOG.md - Version history

🔒 Security & Best Practices

Credential Management:

✅ Use OAuth2 (recommended) or app-specific passwords only
✅ Never use your main Zoho password
✅ Token files automatically secured with 0600 permissions
✅ Never commit credentials to version control

Command Handler Security (if exposing /email commands):

✅ Use email-command-SECURE.js (prevents command injection)
✅ Restrict command access to authorized users only
✅ Add rate limiting at bot level
✅ Enable audit logging for sensitive operations

Verification:

# Check token file permissions (should be 600)
ls -la ~/.clawdbot/zoho-mail-tokens.json
 
# Fix if needed
chmod 600 ~/.clawdbot/zoho-mail-tokens.json

See SECURITY.md for complete security guide.

📖 Quick Examples

Most common Clawdbot-style actions

# Unread count (fast, good for briefings)
python3 scripts/zoho-email.py unread
 
# Search inbox
python3 scripts/zoho-email.py search "invoice"
 
# Read a specific email (folder + id)
python3 scripts/zoho-email.py get INBOX <id>
 
# Send a simple email
python3 scripts/zoho-email.py send recipient@example.com "Subject" "Body text"
 
# Empty Spam (safe by default: DRY RUN)
python3 scripts/zoho-email.py empty-spam
# Execute for real
python3 scripts/zoho-email.py empty-spam --execute
 
# Empty Trash (safe by default: DRY RUN)
python3 scripts/zoho-email.py empty-trash
# Execute for real
python3 scripts/zoho-email.py empty-trash --execute

Basic Operations

# Get unread count
python3 scripts/zoho-email.py unread
 
# Search emails
python3 scripts/zoho-email.py search "important meeting"
 
# Send email
python3 scripts/zoho-email.py send recipient@example.com "Subject" "Message body"

HTML Emails (v1.1.0+)

# Send HTML email from template
python3 scripts/zoho-email.py send-html user@example.com "Newsletter" templates/newsletter.html
 
# Preview HTML before sending
python3 scripts/zoho-email.py preview-html templates/welcome.html

Attachments (v1.1.0+)

# Send with attachments
python3 scripts/zoho-email.py send user@example.com "Report" "See attached" --attach report.pdf --attach data.xlsx
 
# List attachments in an email
python3 scripts/zoho-email.py list-attachments Inbox 4590
 
# Download attachment
python3 scripts/zoho-email.py download-attachment Inbox 4590 0 ./report.pdf

Batch Operations (v1.1.0+)

# Mark multiple emails as read
python3 scripts/zoho-email.py mark-read INBOX 1001 1002 1003
 
# Delete multiple emails (with confirmation)
python3 scripts/zoho-email.py delete INBOX 2001 2002 2003
 
# Move emails to folder
python3 scripts/zoho-email.py move INBOX "Archive/2024" 3001 3002
 
# Bulk action with search
python3 scripts/zoho-email.py bulk-action \
  --folder INBOX \
  --search 'SUBJECT "newsletter"' \
  --action mark-read \
  --dry-run

OAuth2 & REST API (v1.2.0+, v2.0.0+)

# Set up OAuth2 (one-time)
python3 scripts/oauth-setup.py
 
# Check OAuth2 status
python3 scripts/zoho-email.py oauth-status
 
# Force REST API mode (5-10x faster)
python3 scripts/zoho-email.py unread --api-mode rest --verbose
 
# Force IMAP mode (compatibility)
python3 scripts/zoho-email.py unread --api-mode imap

🧩 Clawdbot Integration (NEW!)

/email Commands (Telegram, Discord, etc.)

Use email directly in Clawdbot messaging platforms via /email commands:

# Check unread count
/email unread
 
# Search your inbox
/email search invoice
 
# Send an email
/email send john@example.com "Hello" "Hi John"
 
# Brief summary (for briefings)
/email summary
 
# Diagnostics
/email doctor
 
# Get help
/email help

Setup:

Copy examples/clawdbot-extension/clawdbot_extension.py to your scripts directory
Set ZOHO_EMAIL environment variable
Run OAuth2 setup: python3 scripts/oauth-setup.py
Test: python3 scripts/clawdbot_extension.py unread

Heartbeat/Cron Integration

Add email summary to morning briefings or scheduled tasks:

# In your heartbeat/cron script
python3 scripts/clawdbot_extension.py summary
 
# Output: 📭 No unread emails
#     OR: 📧 3 unread emails

Examples:

examples/clawdbot-extension/heartbeat-example.md - Complete integration guide
examples/clawdbot-commands/emails.sh - Simple wrapper script

Use Cases

✅ Morning briefings - Add email summary to daily briefing
✅ Slack/Discord alerts - Notify on unread emails
✅ Interactive commands - /email search invoice in chat
✅ Automated workflows - Cron + Clawdbot integration

💡 Use Cases

Morning briefings - Automated unread email summaries
Email monitoring - Watch for VIP senders or keywords
Newsletter cleanup - Bulk-mark newsletters as read
Automated responses - Search and reply to specific emails
Email archiving - Move old emails to archive folders
Notifications - Alert when important emails arrive
HTML campaigns - Send rich-formatted newsletters
Attachment workflows - Download invoices, reports automatically

🔧 Requirements

Minimum:

Python 3.x
Zoho Mail account
App-specific password OR OAuth2 setup

Optional (for REST API mode):

requests>=2.31.0 (install: pip3 install -r requirements.txt)
OAuth2 credentials (automatic 5-10x performance boost)

📦 Version History

v2.0.0 (2025-01-29) - REST API backend with 5-10x performance boost
v1.2.0 (2025-01-29) - OAuth2 authentication with automatic token refresh
v1.1.0 (2025-01-29) - HTML emails, attachments, batch operations
v1.0.0 (2025-01-29) - Initial IMAP/SMTP implementation

See CHANGELOG.md for complete version history.

🤝 Contributing

Contributions are welcome! Here's how you can help:

🐛 Report bugs: Open an issue
💡 Request features: Open an issue
🔧 Submit PRs: Pull requests
⭐ Star the repo: Show your support!

This is an open-source Clawdbot skill maintained by the community.

📄 License

MIT License - see LICENSE for details.

Part of the Clawdbot ecosystem | ClawHub | Documentation