rooti/agent-zero-plugin-ai-mail
Watch
1
0
Fork
You've already forked agent-zero-plugin-ai-mail
 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions
Minimal Agent Zero plugin for reading, searching, and sending email through preconfigured IMAP/SMTP accounts without exposing credentials to the AI.
14 commits 1 branch 2 tags 258 KiB
  • Python 76.3%
  • HTML 13.1%
  • JavaScript 8.6%
  • Shell 2%
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Lyra 2489c95e37 docs: remove provider domain from AGENTS.md 
Drop the provider-name example from the preset line to keep
agent guidance free of provider-identifying details.
Functional preset data in `helpers/provider_presets.py`
is unchanged.
2026-09-15 09:31:22 +02:00
api Initial migration: ai_mail plugin to project-based development 2026-05-31 20:59:33 +00:00
helpers feat: add prompt injection protection for email content 2026-07-14 14:23:31 +02:00
prompts feat: add prompt injection protection for email content 2026-07-14 14:23:31 +02:00
tests feat: add prompt injection protection for email content 2026-07-14 14:23:31 +02:00
tools feat: add prompt injection protection for email content 2026-07-14 14:23:31 +02:00
webui Initial migration: ai_mail plugin to project-based development 2026-05-31 20:59:33 +00:00
.gitignore feat: migrate ai_mail plugin to plugin forge 2026-09-15 09:22:19 +02:00
__init__.py Initial migration: ai_mail plugin to project-based development 2026-05-31 20:59:33 +00:00
AGENTS.md docs: remove provider domain from AGENTS.md 2026-09-15 09:31:22 +02:00
CHANGELOG.md feat: add prompt injection protection for email content 2026-07-14 14:23:31 +02:00
default_config.yaml feat: add prompt injection protection for email content 2026-07-14 14:23:31 +02:00
deploy.sh chore: regenerate deploy.sh for Forge convention 2026-09-15 09:23:52 +02:00
execute.py Initial migration: ai_mail plugin to project-based development 2026-05-31 20:59:33 +00:00
LICENSE Initial migration: ai_mail plugin to project-based development 2026-05-31 20:59:33 +00:00
plugin.yaml chore: bump plugin version to 0.3.0 2026-09-15 09:26:18 +02:00
README.md docs: add SPDX license identifier to readme 2026-09-15 09:26:18 +02:00
thumbnail.jpg Initial migration: ai_mail plugin to project-based development 2026-05-31 20:59:33 +00:00

README.md

AI Mail Plugin

Agent Zero plugin for reading, searching, sending, and trashing email through preconfigured IMAP/SMTP accounts without exposing credentials to the AI.

Quick Start

./deploy.sh deploy

Requires Agent Zero process restart for Python code changes. Config changes (plugin settings, config.json) take effect without restart.

Key Directories

Directory Purpose
tools/ Agent Zero native tool (IMAP/SMTP client)
helpers/ Core logic: IMAP/SMTP clients, models, config, security
tests/ Unit and integration tests
prompts/ Tool prompt documentation for agent system
webui/ Settings screen, account editor modal, config store
api/ API endpoint tests

Key Files

  • plugin.yaml - Plugin manifest (name, version, dependencies)
  • execute.py - Plugin entry point
  • tools/ai_mail.py - Agent Zero tool (list, search, send, trash)
  • helpers/mail_service.py - Mail service orchestration
  • helpers/imap_client.py - IMAP client wrapper with injectable transports
  • helpers/smtp_client.py - SMTP client wrapper with injectable transports
  • helpers/content_security.py - Prompt injection protection for email content
  • helpers/config.py - Plugin config and account normalization
  • helpers/models.py - Account and message data models
  • default_config.yaml - Default configuration template
  • deploy.sh - Build, deploy, validate, and zip script

Tech Stack

Python 3.12+ | IMAP | SMTP | Flask | Alpine.js

Notes

  • Accounts are configured in plugin settings, not by the AI; the AI only sees account summaries, account IDs, rights, and account context.
  • Per-account permissions are independent: can_read, can_send, can_delete. An account may be read-only, send-only, or allow trashing without sending.
  • Message selection uses folder + uid; Message-ID is not part of the AI-facing API.
  • Outgoing recipient whitelist is global, exact addresses only, case-insensitive. Applies to to, cc, and bcc.
  • Trash handling supports manual mode (configured trash_folder) and auto mode (IMAP special-use discovery, legacy XLIST, mailbox name heuristics). Detected folder is persisted as a cache.
  • Search targets exactly one folder per request. search_in supports subject, body, from, to with OR logic for multiple areas.
  • Content security: email content framing, injection pattern neutralization, control character stripping, body length limiting.
  • No attachment download or sending in the current implementation.
  • Hard-delete is not exposed to the AI; only move-to-trash is supported.
  • SPDX-License-Identifier: MIT