openclaw-email

CLI email tools for OpenClaw agents — reliable IMAP/SMTP with full search.

Drop-in replacement for himalaya, built for AI agent automation. No TTY prompts, no crashes, no mail-parser segfaults.

Features

• Full IMAP search — OR/AND/NOT criteria, date ranges, sender/subject filters
• Reliable SMTP send — with automatic IMAP Sent folder save
• JSON output — machine-readable for agent pipelines
• No TTY prompts — headless-first design
• No crashes — pure Python, no native mail-parser dependency
• Attachments — send files, list attachment metadata on read

Installation

pip install imap_tools

Copy read-email.py and send-email.py to your scripts directory.

Configuration

Option 1: Config file

Create ~/.config/openclaw-email/config.json:

{
  "imap_host": "mail.example.com",
  "smtp_host": "mail.example.com",
  "address": "you@example.com",
  "password": "your-password",
  "smtp_port": 465,
  "imap_port": 993,
  "from_name": "Your Name",
  "sent_folder": "Sent"
}

Option 2: Environment variables

export EMAIL_IMAP_HOST=mail.example.com
export EMAIL_SMTP_HOST=mail.example.com
export EMAIL_ADDRESS=you@example.com
export EMAIL_PASSWORD=your-password
export EMAIL_SMTP_PORT=465
export EMAIL_IMAP_PORT=993
export EMAIL_FROM_NAME="Your Name"
export EMAIL_SENT_FOLDER=Sent

Config file values are loaded first, then env vars override them.

Usage

List emails

# List recent emails
python3 read-email.py list

# List unread only, as JSON
python3 read-email.py list --unread --json

# List from specific folder
python3 read-email.py list --folder INBOX.Archive --limit 50

Search emails

# Search by sender
python3 read-email.py search --from "wolt.com"

# Search by subject and date range
python3 read-email.py search --subject "invoice" --since 2025-01-01 --before 2025-02-01

# OR logic (match any criteria)
python3 read-email.py search --from "wolt" --from "uber" --or --json

# Unread + flagged
python3 read-email.py search --unread --flagged

Read a message

# Read by UID (human-readable)
python3 read-email.py read 12345

# Read as JSON (includes text, html, attachments)
python3 read-email.py read 12345 --json

# Get raw HTML body
python3 read-email.py read 12345 --html

# Show raw headers
python3 read-email.py read 12345 --headers

List folders

python3 read-email.py folders

Move a message

python3 read-email.py move 12345 INBOX.Trash

Send email

# Simple send
python3 send-email.py --to "recipient@example.com" --subject "Hello" --body "Message body"

# Send with attachment
python3 send-email.py --to "recipient@example.com" --subject "Report" --body "See attached" --attach report.pdf

# Read body from stdin
echo "Hello from pipeline" | python3 send-email.py --to "recipient@example.com" --subject "Pipeline output"

# Reply to a message
python3 send-email.py --to "recipient@example.com" --subject "Re: Topic" --body "Reply text" --reply-to "<message-id@example.com>"

Why not himalaya?

Himalaya is great in theory but has practical issues for AI agent use:

• mail-parser crashes — segfaults on certain emails, killing the entire pipeline
• TTY prompts — asks for input when auth fails, hanging headless agents
• Complex config — TOML config with account profiles, overkill for single-account use
• Rust binary — harder to debug and modify than Python scripts

These scripts are ~200 lines each, easy to understand and modify.

License

MIT