vrr/agent-zero
2
0
Fork 0
mirror of https://github.com/agent0ai/agent-zero.git synced 2026-10-15 16:29:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
agent-zero/plugins/_email_integration
History
Alessandro ccb63de564 Improve Email plugin settings experience 
Enable project and agent-profile scoped configuration, add a token-native status page, and replace the custom advanced panel with the shared accordion.
2026-09-12 17:28:23 +02:00
..
api Improve Email plugin settings experience 2026-09-12 17:28:23 +02:00
extensions/python Refactor: use user locale for time displays 2026-05-21 15:26:00 +02:00
helpers Fix IMAP sender whitelist bypass with strict mailbox parsing 2026-09-09 13:54:54 +02:00
prompts Squashed commit of the following: 2026-03-31 09:47:25 +02:00
webui Improve Email plugin settings experience 2026-09-12 17:28:23 +02:00
AGENTS.md Improve Email plugin settings experience 2026-09-12 17:28:23 +02:00
default_config.yaml Polish onboarding and email setup UX 2026-04-27 03:00:09 +02:00
plugin.yaml Improve Email plugin settings experience 2026-09-12 17:28:23 +02:00
README.md Fix IMAP sender whitelist bypass with strict mailbox parsing 2026-09-09 13:54:54 +02:00

README.md

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.
  • Sender filtering
    • IMAP requires exactly one valid From mailbox, even when the sender whitelist is empty.
    • Whitelist patterns match the mailbox address, excluding display names; replies use that same address.
    • This filters the claimed From address, not authenticated identity. Sender authenticity requires checks enforced by your mail provider.
  • 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.