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

# 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="[email protected]"

# 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

If you don't want OAuth2 yet:

export ZOHO_EMAIL="[email protected]"
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

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

⚡ 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

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

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.

# 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 [email protected] "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

# 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 [email protected] "Subject" "Message body"

# Send HTML email from template
python3 scripts/zoho-email.py send-html [email protected] "Newsletter" templates/newsletter.html

# Preview HTML before sending
python3 scripts/zoho-email.py preview-html templates/welcome.html

# Send with attachments
python3 scripts/zoho-email.py send [email protected] "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

# 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

# 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

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 [email protected] "Hello" "Hi John"

# Brief summary (for briefings)
/email summary

# Diagnostics
/email doctor

# Get help
/email help

Setup:

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

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

✅ 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

• 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

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)

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

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.

MIT License - see LICENSE for details.

Part of the Clawdbot ecosystem | ClawHub | Documentation