E-Mail Companion

<img src="webui/thumbnail.webp" width="128" height="128" alt="E-Mail Companion icon" align="right"/>

Safe, controlled mailbox access for Agent Zero.

Let your agent read, triage, and draft emails — without ever sending, deleting, or moving anything unless you explicitly approve it.

---

Why This Plugin?

Email is dangerous for AI agents. A crafted message can trick an agent into executing instructions buried in mail content. This plugin makes mailbox work safe by design:

• 🔒 Read-only by default — the agent can browse and search your inbox, but cannot change anything
• 📝 Drafts, not sends — replies are prepared locally; you review before anything goes out
• ✅ Explicit approval required — every send, delete, move, or flag goes through a modal you must click
• 🛡️ Prompt-injection defense — all mail content is sanitized and wrapped in <UNTRUSTED_EMAIL> tags
• 🤖 Bundled Mail Agent — isolated subordinate profile for safe mail triage and draft preparation
• 🔍 Full audit trail — every action is logged without storing mail bodies or credentials

What It Does

Capability	How It Works
Browse inbox	List folders, search envelopes, read message bodies (without marking as seen)
Draft replies	Create, view, and manage local email drafts as JSON + EML files
Approve actions	Propose send/delete/move/flag → user gets a modal with full preview → approve or reject
Audit log	JSONL log of every action (no bodies, no credentials)

Requirements

Before installing, you need:

1. himalaya v2+ — a CLI email client

   • Install: brew install himalaya (macOS) or build from source
   • Configure: create ~/.config/himalaya/config.toml with your IMAP/SMTP credentials
   • Verify: himalaya envelope list should return your inbox

2. Agent Zero with the ask_user_question plugin

   • The approval modal uses ask_user_question for structured yes/no dialogs
   • Install it from the Plugin Hub if you don't have it

3. markdown Python library (auto-installed by plugin hook)

   • Used for Markdown→HTML conversion in draft bodies
   • If not available, wrapper falls back to <pre> text wrapping
   • Manual install: pip install markdown

Installation

Option A: Plugin Hub (recommended)

1. Open Agent Zero → Plugins → Browse
2. Search for "E-Mail Companion"
3. Click Install

Option B: Manual

cp -r email_companion/ /path/to/agent-zero/usr/plugins/

Then restart Agent Zero.

How To Use

Just talk to your agent naturally:

• "Show me the latest 10 emails"
• "Search for messages from john@example.com"
• "Read the email with UID 42"
• "Draft a reply to UID 42 saying I'll review the proposal by Friday"
• "Send the draft to john@example.com" → the agent will ask for your approval before sending

Approval Workflow

When the agent wants to send, delete, move, or flag an email:

1. It creates a proposal (local JSON file, no server action yet)
2. A modal appears showing the full draft or mutation details
3. You click Approve or Reject
4. Only after approval does the agent execute the real command via himalaya

If you don't respond or the modal times out, nothing happens.

Security Model

Tier	Actions	Default Behavior
Read	folders, list, search, fetch	✅ Allowed (fetch does not mark as seen)
Local	draft-create, draft-list, draft-show, draft-delete	✅ Allowed
Mutation	send, delete, move, copy, flag, mark-read, archive	⛔ Blocked → requires approval

Key guarantees:

• Mail content is always treated as untrusted data, never as instructions
• HTML is converted to plain text; control/Bidi characters are stripped
• No mail bodies, attachments, or credentials are stored in memory, logs, or knowledge
• The wrapper uses a strict allowlist — unknown commands are rejected

Plugin Structure

email_companion/
├── plugin.yaml                          # Manifest
├── agents/mail-agent/                   # Bundled subordinate agent profile
│   ├── agent.yaml
│   └── prompts/agent.system.main.specifics.md
├── scripts/himalaya_wrapper.py          # Hardened CLI wrapper
├── tools/email_companion.py             # Agent Zero native tool
├── skills/email-companion/SKILL.md      # Agent skill with workflow docs
├── prompts/agent.system.tool.email_companion.md
├── tests/test_himalaya_wrapper.py       # 18 unit tests
└── webui/thumbnail.webp                 # Marketplace icon

Configuration

The wrapper auto-detects himalaya from your system PATH. Data files (drafts, approvals, audit log) are stored in the plugin's .a0proj/data/ directory.

To override the data directory:

export EMAIL_COMPANION_DATA_DIR=/custom/path

Testing

cd usr/plugins/email_companion
python -m unittest tests.test_himalaya_wrapper -v

All 11 tests should pass.

License

MIT