ClawHub

Mail

Execute email operations with platform-specific optimizations and secure credential handling.

Audits

Pass
ClawScanPass

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install mail

Requirements

Binaries:

  • himalaya - IMAP/SMTP CLI (brew install himalaya or cargo install himalaya)
  • osascript - macOS only, built-in

Credentials:

  • App Password for Gmail (not regular password), stored in macOS Keychain
  • Configure in ~/.config/himalaya/config.toml

Data Access

Read-only paths:

  • ~/Library/Mail/V*/MailData/Envelope Index - Apple Mail SQLite database (macOS only)
  • ~/Library/Mail/V*/MAILBOX/Messages/ - attachment files (macOS only)

Scope

This skill:

  • ✅ Reads email via himalaya CLI or Apple Mail SQLite
  • ✅ Sends email via himalaya (draft-review-send workflow)
  • ✅ Searches and filters messages
  • ❌ NEVER modifies credentials
  • ❌ NEVER deletes emails without explicit confirmation
  • ❌ NEVER auto-sends without user review

Quick Reference

TopicFile
Apple Mail SQLite queriesapple-mail.md
himalaya CLI patternshimalaya.md
Send/reply protocolsending.md

Core Rules

1. Platform Detection

  • macOS with Apple Mail: Use SQLite queries (100x faster than AppleScript)
  • Cross-platform: Use himalaya CLI for full IMAP/SMTP
  • Never mix approaches in same task - commit to one to avoid state conflicts

2. Apple Mail SQLite

  • Query path: ~/Library/Mail/V*/MailData/Envelope\ Index
  • Force sync first: osascript -e 'tell app "Mail" to check for new mail' - SQLite reads stale data otherwise
  • Recent mail filter: WHERE date_received > strftime('%s','now','-7 days')
  • Join messages→addresses on message_id for sender lookup

3. himalaya CLI

  • Always use: --output json flag for programmatic parsing
  • List emails: himalaya envelope list -o json (NOT message list)
  • Folder names are case-sensitive
  • Run himalaya folder list after server-side folder changes

4. Send Protocol

  • Draft-review-send workflow: Compose → show user full content → send after explicit OK
  • Reply threading: Include In-Reply-To and References headers or thread breaks
  • Some SMTP servers reject if From header doesn't match authenticated user

5. Credential Management

  • macOS Keychain: security add-internet-password -s imap.gmail.com -a user@gmail.com -w 'app-password'
  • Gmail/Google Workspace: Requires App Password with 2FA enabled
  • OAuth: himalaya supports XOAUTH2 via token_cmd in config.toml

6. Thread Intelligence

  • Thread by In-Reply-To chain, not subject matching
  • "Re:" prefix is unreliable
  • Polling intervals: 15-30 min max; use himalaya envelope watch for real-time