Skip to main content Home Creators johnalbertini14-glitch openclaw-skills zoho-email-integration
zoho-email-integration Complete Zoho Mail integration with OAuth2, REST API (5-10x faster), Clawdbot /email commands, HTML emails, attachments, and batch operations. Security-hardened against path traversal and command injection. Perfect for email automation and workflows.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/johnalbertini14-glitch/openclaw-skills --skill zoho-email-integrationThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository
Related occupations SOC
Based on SOC occupation classification
SECURITY-AUDIT-SUMMARY.md 8.2 KB test-app-password.sh 4.8 KB test-batch-operations.sh 2.6 KB test-rest-api-fixes.sh 3.7 KB name zoho-email-integration description Complete Zoho Mail integration with OAuth2, REST API (5-10x faster), Clawdbot /email commands, HTML emails, attachments, and batch operations. Security-hardened against path traversal and command injection. Perfect for email automation and workflows. homepage https://github.com/briansmith80/clawdbot-zoho-email metadata {"openclaw":{"requires":{"bins":["python3"],"env":["ZOHO_EMAIL","ZOHO_PASSWORD"]},"primaryEnv":"ZOHO_EMAIL","tokenFile":"~/.clawdbot/zoho-mail-tokens.json"}}
Zoho Email Integration
v2.2.6 - Complete Zoho Mail integration with OAuth2 authentication, REST API backend (5-10x faster than IMAP/SMTP), and Clawdbot extension with /email commands for Telegram/Discord . Security-hardened against path traversal and command injection. Supports HTML emails, attachments, batch operations, and advanced automation workflows.
Choose your authentication: OAuth2 (recommended, secure) or app password (simple setup).
๐ Update to Latest Version
clawhub install zoho-email-integration --force
Or update all skills:
clawhub update
๐ Security Notice (v2.2.5+)
CRITICAL FIX: Removed vulnerable JavaScript command handler. If you deployed email-command.js from the examples folder, update immediately:
cp
The vulnerable version used execSync with shell interpolation. The new version uses spawn with argument arrays to prevent command injection.
โจ Features
๐ Authentication & Performance
OAuth2 authentication - Secure token-based auth with automatic refreshREST API backend - 5-10x faster operations than IMAP/SMTPGraceful fallback - Automatically falls back to IMAP if REST API unavailableApp password support - Simple alternative to OAuth2
๐ง Email Operations
๐ฅ Read emails - Fetch from any folder (Inbox, Sent, Drafts, etc.)๐ Smart search - Search by subject, sender, keywords with REST API speed๐ Monitor inbox - Real-time unread count for notifications๐ค Send emails - Plain text or HTML with CC/BCC support๐จ HTML emails - Rich formatting with professional templates included๐ Attachments - Send and download file attachments
โก Batch & Bulk Operations
Batch operations - Mark, delete, or move multiple emails efficientlyBulk actions - Search and act on hundreds of emails at onceDry-run mode - Preview actions before executing for safety
๐ Security
No hardcoded credentials - OAuth2 tokens or environment variables onlyAutomatic token refresh - Seamless token renewalEncrypted connections - SSL/TLS for all operations
๐ฆ Installation clawdhub install zoho-email
Python 3.x
requests library (install: pip3 install requests)Zoho Mail account
โ๏ธ Setup
1. Get an App-Specific Password Important: Don't use your main Zoho password!
Log in to Zoho Mail
Go to Settings โ Security โ App Passwords
Generate a new app password for "Clawdbot" or "IMAP/SMTP Access"
Copy the password (you'll need it next)
2. Configure Credentials Option A: Environment Variables
Export your Zoho credentials:
export ZOHO_EMAIL="your-email@domain.com"
export ZOHO_PASSWORD="your-app-specific-password"
Option B: Credentials File
Create ~/.clawdbot/zoho-credentials.sh:
#!/bin/bash
export ZOHO_EMAIL="your-email@domain.com"
export ZOHO_PASSWORD="your-app-specific-password"
Make it executable and secure:
chmod 600 ~/.clawdbot/zoho-credentials.sh
Then source it before running:
source ~/.clawdbot/zoho-credentials.sh
3. Test Connection python3 scripts/zoho-email.py unread
๐ Usage All commands require credentials set via environment variables.
Quick commands (common tasks)
python3 scripts/zoho-email.py doctor
python3 scripts/zoho-email.py unread
python3 scripts/zoho-email.py search "invoice"
python3 scripts/zoho-email.py get INBOX <id >
python3 scripts/zoho-email.py send recipient@example.com "Subject" "Body text"
python3 scripts/zoho-email.py empty-spam
python3 scripts/zoho-email.py empty-spam --execute
python3 scripts/zoho-email.py empty-trash
python3 scripts/zoho-email.py empty-trash --execute
Send HTML Emails Send rich, formatted HTML emails with multipart/alternative support (both HTML and plain text versions):
python3 scripts/zoho-email.py send-html recipient@example.com "Newsletter" examples/templates/newsletter.html
python3 scripts/zoho-email.py send-html recipient@example.com "Welcome" "<h1>Hello!</h1><p>Welcome to our service.</p>"
python3 scripts/zoho-email.py preview-html examples/templates/newsletter.html
from scripts.zoho_email import ZohoEmail
zoho = ZohoEmail()
zoho.send_html_email(
to="recipient@example.com" ,
subject="Newsletter" ,
html_body="<h1>Hello!</h1><p>Welcome!</p>"
)
zoho.send_email(
to="recipient@example.com" ,
subject="Newsletter" ,
body="Plain text version of your email" ,
html_body="<h1>Hello!</h1><p>HTML version of your email</p>"
)
with open ('examples/templates/newsletter.html' , 'r' ) as f:
html_content = f.read()
zoho.send_html_email(
to="recipient@example.com" ,
subject="Monthly Newsletter" ,
html_body=html_content
)
โ
Multipart/alternative emails (HTML + plain text)
โ
Auto-generated plain text fallback
โ
Load HTML from files or inline strings
โ
Preview mode to test before sending
โ
Full CSS styling support
โ
Works with all email clients
Templates:
Pre-built templates available in examples/templates/:
newsletter.html - Professional newsletter layoutannouncement.html - Important announcements with bannerswelcome.html - Onboarding welcome emailsimple.html - Basic HTML template for quick customization
Check Unread Count python3 scripts/zoho-email.py unread
Perfect for morning briefings or notification systems.
Search Inbox python3 scripts/zoho-email.py search "invoice"
Returns last 10 matching emails with subject, sender, date, and body preview.
Search Sent Emails python3 scripts/zoho-email.py search-sent "client name"
Returns last 5 matching sent emails.
Get Specific Email python3 scripts/zoho-email.py get Inbox 4590
python3 scripts/zoho-email.py get Sent 1234
Returns full email content including complete body.
Send Email python3 scripts/zoho-email.py send "client@example.com" "Subject" "Email body here"
Send Email with Attachments python3 scripts/zoho-email.py send "client@example.com" "Invoice" "Please find the invoice attached" --attach invoice.pdf --attach receipt.jpg
Supports multiple attachments with --attach flag.
List Email Attachments python3 scripts/zoho-email.py list-attachments Inbox 4590
Returns JSON with attachment details:
[
{
"index" : 0 ,
"filename" : "invoice.pdf" ,
"content_type" : "application/pdf" ,
"size" : 52341
} ,
{
"index" : 1 ,
"filename" : "receipt.jpg" ,
"content_type" : "image/jpeg" ,
"size" : 128973
}
]
Download Attachment
python3 scripts/zoho-email.py download-attachment Inbox 4590 0
python3 scripts/zoho-email.py download-attachment Inbox 4590 1 my-receipt.jpg
Returns JSON with download details:
{
"filename" : "invoice.pdf" ,
"output_path" : "invoice.pdf" ,
"size" : 52341 ,
"content_type" : "application/pdf"
}
๐ค Clawdbot Integration Examples
Morning Briefing Check unread emails and report:
UNREAD=$(python3 scripts/zoho-email.py unread | jq -r '.unread_count' )
echo "๐ง You have $UNREAD unread emails"
Email Monitoring RESULTS=$(python3 scripts/zoho-email.py search "Important Client" )
COUNT=$(echo "$RESULTS " | jq '. | length' )
if [ $COUNT -gt 0 ]; then
echo "โ ๏ธ New email from Important Client!"
fi
Automated Responses Search and reply workflow:
EMAIL=$(python3 scripts/zoho-email.py search "invoice" | jq -r '.[0]' )
FROM=$(echo "$EMAIL " | jq -r '.from' )
python3 scripts/zoho-email.py send "$FROM " "Re: Invoice" "Thanks for your inquiry..."
Attachment Workflows Download invoice attachments automatically:
EMAILS=$(python3 scripts/zoho-email.py search "invoice" )
EMAIL_ID=$(echo "$EMAILS " | jq -r '.[0].id' )
ATTACHMENTS=$(python3 scripts/zoho-email.py list-attachments Inbox "$EMAIL_ID " )
echo "$ATTACHMENTS " | jq -r '.[] | select(.content_type == "application/pdf") | .index' | while read INDEX; do
python3 scripts/zoho-email.py download-attachment Inbox "$EMAIL_ID " "$INDEX " "invoice_${INDEX} .pdf"
echo "Downloaded invoice_${INDEX} .pdf"
done
Send report with attachments:
python3 generate_report.py > report.txt
python3 scripts/zoho-email.py send "manager@example.com" "Weekly Report" "Please see attached report" --attach report.txt --attach chart.png
๐ Python API Import the module for programmatic use:
from scripts.zoho_email import ZohoEmail
zoho = ZohoEmail()
results = zoho.search_emails(folder="INBOX" , query='SUBJECT "invoice"' , limit=10 )
email = zoho.get_email(folder="Sent" , email_id="4590" )
zoho.send_email(
to="client@example.com" ,
subject="Hello" ,
body="Message text" ,
cc="manager@example.com"
)
zoho.send_html_email(
to="client@example.com" ,
subject="Newsletter" ,
html_body="<h1>Welcome!</h1><p>Rich HTML content here</p>" ,
text_body="Welcome! Plain text version here"
)
zoho.send_email(
to="client@example.com" ,
subject="Update" ,
body="Plain text version" ,
html_body="<h1>HTML version</h1>" ,
cc="manager@example.com"
)
zoho.send_email_with_attachment(
to="client@example.com" ,
subject="Invoice" ,
body="Please find the invoice attached" ,
attachments=["invoice.pdf" , "receipt.jpg" ],
cc="manager@example.com"
)
attachments = zoho.get_attachments(folder="INBOX" , email_id="4590" )
for att in attachments:
print (f"{att['index' ]} : {att['filename' ]} ({att['size' ]} bytes)" )
result = zoho.download_attachment(
folder="INBOX" ,
email_id="4590" ,
attachment_index=0 ,
output_path="downloaded_file.pdf"
)
count = zoho.get_unread_count()
๐ HTML Email Examples Check out the complete example in examples/send-html-newsletter.py:
python3 examples/send-html-newsletter.py
Sending simple inline HTML
Loading and sending HTML templates
Custom plain text fallbacks
Professional email layouts
from scripts.zoho_email import ZohoEmail
zoho = ZohoEmail()
with open ('examples/templates/welcome.html' , 'r' ) as f:
html = f.read()
zoho.send_html_email(
to="newuser@example.com" ,
subject="๐ Welcome to Our Platform!" ,
html_body=html
)
๐ Folder Reference Common Zoho Mail folders:
INBOX - Main inboxSent - Sent emailsDrafts - Draft emailsSpam - Spam folderTrash - Deleted emailsCustom folders (e.g., INBOX/ClientName)
๐ง Advanced Configuration Override default IMAP/SMTP servers (if using Zoho Mail self-hosted):
export ZOHO_IMAP="imap.yourdomain.com"
export ZOHO_SMTP="smtp.yourdomain.com"
export ZOHO_IMAP_PORT="993"
export ZOHO_SMTP_PORT="465"
โ Troubleshooting
Authentication Failed
Ensure IMAP is enabled in Zoho Mail settings
Use an app-specific password , not your main password
Verify credentials are properly exported
Connection Timeout
Check firewall allows port 993 (IMAP) and 465 (SMTP)
Verify Zoho Mail server status
Try with a different network (corporate firewalls may block IMAP)
Search Returns No Results
IMAP search is case-insensitive
Try broader keywords
Verify folder name is correct (case-sensitive)
"ZOHO_EMAIL and ZOHO_PASSWORD must be set" You forgot to export credentials! Run:
export ZOHO_EMAIL="your-email@domain.com"
export ZOHO_PASSWORD="your-app-password"
๐ฃ๏ธ Roadmap
โ
Completed (v2.0.0)
๐ฎ Future Enhancements
๐ Notes
Search limit: Returns last 5-10 emails by default (configurable in code)Body truncation: Search results show first 500 charactersEncoding: Handles UTF-8 and various email encodingsSecurity: Credentials never leave your system except to Zoho servers
๐ค Contributing Found a bug or want to contribute? Submit issues or PRs on GitHub!
๐ License MIT License - free to use, modify, and distribute.
Created: 2026-01-29Status: Production-ready โ
Requires: Python 3.x. For REST API mode: pip install -r requirements.txt (includes requests).
๐ Batch Operations New in v1.1! Process multiple emails efficiently with batch commands.
Mark Multiple Emails as Read python3 scripts/zoho-email.py mark-read INBOX 1001 1002 1003
Mark several emails as read in one command. Perfect for clearing notifications.
Mark Multiple Emails as Unread python3 scripts/zoho-email.py mark-unread INBOX 1004 1005
Flag important emails to revisit later.
Delete Multiple Emails python3 scripts/zoho-email.py delete INBOX 2001 2002 2003
Safety: Asks for confirmation before deleting. Emails are moved to Trash (not permanently deleted).
Move Emails Between Folders python3 scripts/zoho-email.py move INBOX "Archive/2024" 3001 3002 3003
Organize emails by moving them to custom folders.
Bulk Actions with Search Perform actions on all emails matching a search query:
python3 scripts/zoho-email.py bulk-action \
--folder INBOX \
--search 'SUBJECT "newsletter"' \
--action mark-read \
--dry-run
python3 scripts/zoho-email.py bulk-action \
--folder INBOX \
--search 'SUBJECT "newsletter"' \
--action mark-read
mark-read - Mark all matching emails as readmark-unread - Mark all matching emails as unreaddelete - Move all matching emails to Trash
--search 'SUBJECT "invoice"'
--search 'FROM "sender@example.com"'
--search 'UNSEEN'
--search '(SUBJECT "urgent" FROM "boss@company.com")'
--search 'SINCE 01-Jan-2024'
Batch Operations in Python from scripts.zoho_email import ZohoEmail
zoho = ZohoEmail()
result = zoho.mark_as_read(['1001' , '1002' , '1003' ], folder="INBOX" )
print (f"Success: {len (result['success' ])} , Failed: {len (result['failed' ])} " )
result = zoho.delete_emails(['2001' , '2002' ], folder="INBOX" )
result = zoho.move_emails(
email_ids=['3001' , '3002' ],
target_folder="Archive/2024" ,
source_folder="INBOX"
)
result = zoho.bulk_action(
query='SUBJECT "newsletter"' ,
action='mark-read' ,
folder="INBOX" ,
dry_run=True
)
print (f"Found {result['total_found' ]} emails" )
print (f"Will process {result['to_process' ]} emails" )
result = zoho.bulk_action(
query='SUBJECT "newsletter"' ,
action='mark-read' ,
folder="INBOX" ,
dry_run=False
)
Batch Cleanup Example Clean up old newsletters automatically:
python3 scripts/zoho-email.py bulk-action \
--folder INBOX \
--search 'SUBJECT "newsletter"' \
--action delete \
--dry-run
python3 scripts/zoho-email.py bulk-action \
--folder INBOX \
--search 'SUBJECT "newsletter"' \
--action delete
See examples/batch-cleanup.py for a complete automated cleanup script.
