Email Integration

Communicate with Agent Zero through email inboxes and send replies back over SMTP.

What It Does

This plugin polls configured mailboxes, downloads incoming messages and attachments, decides whether a message should continue an existing chat or start a new one, and sends replies back by email.

It supports both:

IMAP inbox polling
Exchange inbox polling
SMTP replies

Main Behavior

Mailbox polling
- Tracks per-handler mailbox state in usr/email/state.json.
- Uses UID tracking for IMAP accounts so only new mail is processed after initialization.
Attachment handling
- Downloads attachments into usr/email/attachments.
Dispatcher workflow
- Reuses or creates a background Email Dispatcher context.
- Uses model prompts to decide whether an email belongs to an existing chat or should open a new one.
- Supports handler-level model presets for new chats, in addition to the dispatcher's utility/chat routing mode.
Thread routing
- Can continue an existing chat by thread ID found in the email subject.
- Falls back to model-based dispatch if no direct thread match is available.
- Email replies inside an existing Agent Zero thread can use /project, /config, and /send control commands.
Notifications and persistence
- Saves chats after routing and emits notifications about new or continued conversations.

Key Files

Core orchestration
- helpers/handler.py manages polling, state persistence, dispatching, and reply flow.
Mail helpers
- helpers/imap_client.py handles IMAP and Exchange fetching.
- helpers/smtp_client.py handles outbound replies.
- helpers/dispatcher.py formats chat summaries and parses dispatcher decisions.
API and extensions
- api/ and extensions/ connect the polling loop and UI-facing operations into the main app.

Configuration Scope

Settings section: external
Per-project config: false
Per-agent config: false

Plugin Metadata

Name: _email_integration
Title: Email Integration
Description: Communicate with Agent Zero via email. Supports IMAP/Exchange inbox polling with SMTP replies.