zoho-email-integration

---
name: zoho-email
description: Complete Zoho Mail integration with OAuth2, REST API (5-10x faster), Clawdbot /email commands, HTML emails, attachments, and batch operations. Perfect for email automation and workflows.
homepage: https://github.com/briansmith80/clawdbot-zoho-email
---

# Zoho Email Integration

**v2.1** - 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**. Supports HTML emails, attachments, batch operations, and advanced automation workflows.

Choose your authentication: OAuth2 (recommended, secure) or app password (simple setup).

## ✨ Features

### 🔐 Authentication & Performance
- **OAuth2 authentication** - Secure token-based auth with automatic refresh
- **REST API backend** - 5-10x faster operations than IMAP/SMTP
- **Graceful fallback** - Automatically falls back to IMAP if REST API unavailable
- **App 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 efficiently
- **Bulk actions** - Search and act on hundreds of emails at once
- **Dry-run mode** - Preview actions before executing for safety

### 🔒 Security
- **No hardcoded credentials** - OAuth2 tokens or environment variables only
- **Automatic token refresh** - Seamless token renewal
- **Encrypted connections** - SSL/TLS for all operations

## 📦 Installation

```bash
clawdhub install zoho-email
```

**Requirements:**
- 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!

1. Log in to Zoho Mail
2. Go to **Settings** → **Security** → **App Passwords**
3. Generate a new app password for "Clawdbot" or "IMAP/SMTP Access"
4. Copy the password (you'll need it next)

### 2. Configure Credentials

**Option A: Environment Variables**

Export your Zoho credentials:

```bash
export ZOHO_EMAIL="your-email@domain.com"
export ZOHO_PASSWORD="your-app-specific-password"
```

**Option B: Credentials File**

Create `~/.clawdbot/zoho-credentials.sh`:

```bash
#!/bin/bash
export ZOHO_EMAIL="your-email@domain.com"
export ZOHO_PASSWORD="your-app-specific-password"
```

Make it executable and secure:
```bash
chmod 600 ~/.clawdbot/zoho-credentials.sh
```

Then source it before running:
```bash
source ~/.clawdbot/zoho-credentials.sh
```

### 3. Test Connection

```bash
python3 scripts/zoho-email.py unread
```

Expected output:
```json
{"unread_count": 5}
```

## 🚀 Usage

All commands require credentials set via environment variables.

### Quick commands (common tasks)

```bash
# Diagnose setup (recommended first step)
python3 scripts/zoho-email.py doctor

# Unread count (great for briefings)
python3 scripts/zoho-email.py unread

# Search inbox
python3 scripts/zoho-email.py search "invoice"

# Get 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
```

### Send HTML Emails

Send rich, formatted HTML emails with multipart/alternative support (both HTML and plain text versions):

**CLI Command:**
```bash
# Send HTML from a file
python3 scripts/zoho-email.py send-html recipient@example.com "Newsletter" examples/templates/newsletter.html

# Send HTML from inline text
python3 scripts/zoho-email.py send-html recipient@example.com "Welcome" "<h1>Hello!</h1><p>Welcome to our service.</p>"

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

**Python API:**
```python
from scripts.zoho_email import ZohoEmail

zoho = ZohoEmail()

# Method 1: Send HTML with auto-generated plain text fallback
zoho.send_html_email(
    to="recipient@example.com",
    subject="Newsletter",
    html_body="<h1>Hello!</h1><p>Welcome!</p>"
)

# Method 2: Send HTML with custom plain text version
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>"
)

# Load HTML from template file
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
)
```

**Features:**
- ✅ 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 layout
- `announcement.html` - Important announcements with banners
- `welcome.html` - Onboarding welcome email
- `simple.html` - Basic HTML template for quick customization

### Check Unread Count

```bash
python3 scripts/zoho-email.py unread
```

Perfect for morning briefings or notification systems.

### Search Inbox

```bash
python3 scripts/zoho-email.py search "invoice"
```

Returns last 10 matching emails with subject, sender, date, and body preview.

### Search Sent Emails

```bash
python3 scripts/zoho-email.py search-sent "client name"
```

Returns last 5 matching sent emails.

### Get Specific Email

```bash
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

```bash
python3 scripts/zoho-email.py send "client@example.com" "Subject" "Email body here"
```

### Send Email with Attachments

```bash
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

```bash
python3 scripts/zoho-email.py list-attachments Inbox 4590
```

Returns JSON with attachment details:
```json
[
  {
    "index": 0,
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "size": 52341
  },
  {
    "index": 1,
    "filename": "receipt.jpg",
    "content_type": "image/jpeg",
    "size": 128973
  }
]
```

### Download Attachment

```bash
# Download first attachment (index 0) with original filename
python3 scripts/zoho-email.py download-attachment Inbox 4590 0

# Download second attachment (index 1) with custom filename
python3 scripts/zoho-email.py download-attachment Inbox 4590 1 my-receipt.jpg
```

Returns JSON with download details:
```json
{
  "filename": "invoice.pdf",
  "output_path": "invoice.pdf",
  "size": 52341,
  "content_type": "application/pdf"
}
```

## 🤖 Clawdbot Integration Examples

### Morning Briefing

Check unread emails and report:

```bash
UNREAD=$(python3 scripts/zoho-email.py unread | jq -r '.unread_count')
echo "📧 You have $UNREAD unread emails"
```

### Email Monitoring

Watch for VIP emails:

```bash
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:

```bash
# Find latest invoice inquiry
EMAIL=$(python3 scripts/zoho-email.py search "invoice" | jq -r '.[0]')
FROM=$(echo "$EMAIL" | jq -r '.from')

# Send reply
python3 scripts/zoho-email.py send "$FROM" "Re: Invoice" "Thanks for your inquiry..."
```

### Attachment Workflows

Download invoice attachments automatically:

```bash
# Search for invoice emails
EMAILS=$(python3 scripts/zoho-email.py search "invoice")

# Get latest email ID
EMAIL_ID=$(echo "$EMAILS" | jq -r '.[0].id')

# List attachments
ATTACHMENTS=$(python3 scripts/zoho-email.py list-attachments Inbox "$EMAIL_ID")

# Download all PDF attachments
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:

```bash
# Generate report
python3 generate_report.py > report.txt

# Send with attachment
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:

```python
from scripts.zoho_email import ZohoEmail

zoho = ZohoEmail()

# Search emails
results = zoho.search_emails(folder="INBOX", query='SUBJECT "invoice"', limit=10)

# Get specific email
email = zoho.get_email(folder="Sent", email_id="4590")

# Send plain text email
zoho.send_email(
    to="client@example.com",
    subject="Hello",
    body="Message text",
    cc="manager@example.com"  # optional
)

# Send HTML email (auto-generated plain text fallback)
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"  # optional, auto-generated if not provided
)

# Send multipart email (HTML + custom pl

... (truncated)