From 8bf006b778d5fb4cc1a2ddb08f6c1adccd5362b3 Mon Sep 17 00:00:00 2001 From: rx Date: Wed, 15 Apr 2026 10:57:32 +0200 Subject: [PATCH 1/3] feat: add AgentMail plugin listing (v1.1.0) --- plugins/agentmail/index.yaml | 7 +++++++ plugins/agentmail/thumbnail.png | Bin 0 -> 7907 bytes 2 files changed, 7 insertions(+) create mode 100644 plugins/agentmail/index.yaml create mode 100644 plugins/agentmail/thumbnail.png diff --git a/plugins/agentmail/index.yaml b/plugins/agentmail/index.yaml new file mode 100644 index 0000000..461b31b --- /dev/null +++ b/plugins/agentmail/index.yaml @@ -0,0 +1,7 @@ +title: AgentMail Integration +description: Send and receive emails via the AgentMail API with attachments, thread replies, and automated agent-powered email processing. +github: https://github.com/Raleksand/agentmail +tags: + - email + - integration + - automation diff --git a/plugins/agentmail/thumbnail.png b/plugins/agentmail/thumbnail.png new file mode 100644 index 0000000000000000000000000000000000000000..18b43bd637d5a4ab7b16e0c2dded309ef8d84df9 GIT binary patch literal 7907 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 Date: Thu, 16 Apr 2026 19:40:58 +0200 Subject: [PATCH 2/3] =?UTF-8?q?feat:=20AgentMail=20plugin=20v1.2.0=20?= =?UTF-8?q?=E2=80=94=20thread=20continuity,=20outbox=20attachments?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- plugins/agentmail/README.md | 143 ++++++++++++++++++++++++++++++++++ plugins/agentmail/index.yaml | 2 +- plugins/agentmail/plugin.yaml | 8 ++ 3 files changed, 152 insertions(+), 1 deletion(-) create mode 100644 plugins/agentmail/README.md create mode 100644 plugins/agentmail/plugin.yaml diff --git a/plugins/agentmail/README.md b/plugins/agentmail/README.md new file mode 100644 index 0000000..3bff7b6 --- /dev/null +++ b/plugins/agentmail/README.md @@ -0,0 +1,143 @@ +# AgentMail Integration + +AgentMail Integration is an Agent Zero plugin for sending and receiving email through the [AgentMail API](https://agentmail.to/), including attachments, thread support, and conversation continuity. + +## Features + +- **Send email** — plain text, HTML, or both +- **Attachments** — send any file type as a Base64-encoded attachment +- **Thread replies** — reply within an existing email thread using `thread_id` +- **Thread continuity** — agent retains conversation context across emails in the same thread +- **Outbox attachments** — agent can save files that are automatically attached to reply emails +- **List inboxes & messages** — browse available inboxes and read messages +- **Get message** — retrieve a single message by ID +- **Download attachments** — programmatically download and decode email attachments +- **Auto-reply (poller)** — process incoming emails automatically via a cron-based poller +- **Per-agent configuration** — each agent can use its own API key, base URL, and default inbox + +## Plugin Files + +| File | Purpose | +|------|----------| +| `plugin.yaml` | Plugin metadata | +| `tools/agentmail_tool.py` | Agent Zero tool implementation | +| `helpers/agentmail_client.py` | AgentMail API client (send, list, get, download attachments) | +| `api/process_email.py` | Loopback endpoint for email-to-agent processing (thread continuity + outbox) | +| `extensions/python/system_prompt/_20_agentmail_context.py` | System prompt override for email sessions (includes outbox instructions) | +| `prompts/agent.system.tool.agentmail.md` | System-level tool documentation | +| `prompts/agent.mail.tool.agentmail.md` | Tool-level usage documentation | +| `webui/config.html` | Plugin configuration UI | +| `webui/agentmail-config-store.js` | Config store for the UI | +| `default_config.yaml` | Default configuration values | +| `execute.py` | Installs required runtime dependency (`requests`) | + +## Configuration + +Open **Settings → External → AgentMail Integration** and configure: + +| Field | Description | +|-------|-------------| +| **API Base URL** | Usually `https://api.agentmail.to/v0` | +| **API Key** | Your AgentMail API key | +| **Default Inbox ID** | Inbox used when a tool call omits `inbox_id` | + +## Tool Actions + +| Action | Required args | Optional args | +|--------|---------------|---------------| +| `list_inboxes` | — | `limit` | +| `create_inbox` | — | `email`, `username`, `domain`, `display_name` | +| `send_email` | `inbox_id`, `to` | `subject`, `text`, `html`, `labels`, `attachments`, `thread_id` | +| `list_messages` | `inbox_id` | `limit` | +| `get_message` | `message_id` | — | + +### Attachments + +The `attachments` parameter is a JSON array of objects: + +```json +{ + "content": "", + "filename": "report.pdf", + "content_type": "application/pdf" +} +``` + +- `content` is required — use `base64 -w0` to encode files +- `filename` and `content_type` are optional +- Any file type is supported: PDF, images, documents, ZIP, audio, video, etc. + +### Thread Support + +Use `thread_id` with `send_email` to reply within an existing email thread: + +1. Get the `thread_id` from `list_messages` results +2. Pass it when calling `send_email` + +## Auto-Reply with Poller + +The plugin includes an internal loopback endpoint (`/api/plugins/agentmail/process_email`) that feeds incoming emails to Agent Zero for processing and returns the agent's reply. To automate this, you can set up a cron-based poller. + +### Poller Setup + +1. Place `agentmail_poll_once.py` in your work directory +2. Add a cron job to run it every minute: + +```bash +crontab -e +# Add: +* * * * * /opt/venv/bin/python /a0/usr/workdir/agentmail_poll_once.py >> /a0/usr/workdir/poll.log 2>&1 +``` + +The poller will: +- Check for new unread emails in the configured inbox +- Download and include text attachment content +- Send the email to Agent Zero for processing +- Automatically reply with the agent's response +- Attach any outbox files saved by the agent + +### Thread Continuity + +When an email arrives in an existing thread, the plugin reuses the same Agent Zero context. This means the agent **remembers the full conversation** from previous emails in that thread — no need to repeat context. + +- Thread → Context mapping is persisted in `agentmail_threads.json` +- If the server restarts and the context is lost, a new one is automatically created + +### Outbox Attachments + +The agent can save files to a per-context outbox directory, and they will be **automatically attached** to the reply email: + +1. The system prompt tells the agent the outbox path for the current context +2. The agent saves files there (e.g., translations, reports, generated content) +3. After the agent finishes, all outbox files are collected and attached to the reply +4. The outbox is cleaned up after successful send + +Example — the agent saves a translation: +```python +with open('/a0/usr/workdir/agentmail_outbox/abc123/translation.txt', 'w') as f: + f.write(translated_text) +``` + +### Safety Features + +- File lock prevents concurrent runs +- Email IDs are recorded before processing (prevents re-processing on crash) +- Maximum emails per cycle (default: 5) prevents runaway processing + +## Version History + +| Version | Changes | +|---------|---------| +| 1.2.0 | Thread continuity (context reuse across emails), outbox attachments, updated system prompt | +| 1.1.0 | Attachment support, thread_id for replies, attachment download in client | +| 1.0.0 | Initial release — send/receive emails, auto-reply poller | + +## Notes + +- The plugin is intended to run inside Agent Zero +- The internal processing endpoint is for loopback use only (127.0.0.1) +- The poller script is deployment-specific and lives outside the plugin directory + +## License + +MIT diff --git a/plugins/agentmail/index.yaml b/plugins/agentmail/index.yaml index 461b31b..f1ae3ed 100644 --- a/plugins/agentmail/index.yaml +++ b/plugins/agentmail/index.yaml @@ -1,5 +1,5 @@ title: AgentMail Integration -description: Send and receive emails via the AgentMail API with attachments, thread replies, and automated agent-powered email processing. +description: Send and receive emails with thread continuity and outbox attachments via the AgentMail API. github: https://github.com/Raleksand/agentmail tags: - email diff --git a/plugins/agentmail/plugin.yaml b/plugins/agentmail/plugin.yaml new file mode 100644 index 0000000..e77b0bd --- /dev/null +++ b/plugins/agentmail/plugin.yaml @@ -0,0 +1,8 @@ +name: agentmail +title: AgentMail Integration +description: Send and receive emails via the AgentMail API. +version: 1.2.0 +settings_sections: + - external +per_project_config: false +per_agent_config: true From 78115baf9358af28c7edf0591f933529d6e67c0e Mon Sep 17 00:00:00 2001 From: rx Date: Thu, 16 Apr 2026 20:00:20 +0200 Subject: [PATCH 3/3] fix: keep only allowed files in plugin index folder --- plugins/agentmail/README.md | 143 ---------------------------------- plugins/agentmail/plugin.yaml | 8 -- 2 files changed, 151 deletions(-) delete mode 100644 plugins/agentmail/README.md delete mode 100644 plugins/agentmail/plugin.yaml diff --git a/plugins/agentmail/README.md b/plugins/agentmail/README.md deleted file mode 100644 index 3bff7b6..0000000 --- a/plugins/agentmail/README.md +++ /dev/null @@ -1,143 +0,0 @@ -# AgentMail Integration - -AgentMail Integration is an Agent Zero plugin for sending and receiving email through the [AgentMail API](https://agentmail.to/), including attachments, thread support, and conversation continuity. - -## Features - -- **Send email** — plain text, HTML, or both -- **Attachments** — send any file type as a Base64-encoded attachment -- **Thread replies** — reply within an existing email thread using `thread_id` -- **Thread continuity** — agent retains conversation context across emails in the same thread -- **Outbox attachments** — agent can save files that are automatically attached to reply emails -- **List inboxes & messages** — browse available inboxes and read messages -- **Get message** — retrieve a single message by ID -- **Download attachments** — programmatically download and decode email attachments -- **Auto-reply (poller)** — process incoming emails automatically via a cron-based poller -- **Per-agent configuration** — each agent can use its own API key, base URL, and default inbox - -## Plugin Files - -| File | Purpose | -|------|----------| -| `plugin.yaml` | Plugin metadata | -| `tools/agentmail_tool.py` | Agent Zero tool implementation | -| `helpers/agentmail_client.py` | AgentMail API client (send, list, get, download attachments) | -| `api/process_email.py` | Loopback endpoint for email-to-agent processing (thread continuity + outbox) | -| `extensions/python/system_prompt/_20_agentmail_context.py` | System prompt override for email sessions (includes outbox instructions) | -| `prompts/agent.system.tool.agentmail.md` | System-level tool documentation | -| `prompts/agent.mail.tool.agentmail.md` | Tool-level usage documentation | -| `webui/config.html` | Plugin configuration UI | -| `webui/agentmail-config-store.js` | Config store for the UI | -| `default_config.yaml` | Default configuration values | -| `execute.py` | Installs required runtime dependency (`requests`) | - -## Configuration - -Open **Settings → External → AgentMail Integration** and configure: - -| Field | Description | -|-------|-------------| -| **API Base URL** | Usually `https://api.agentmail.to/v0` | -| **API Key** | Your AgentMail API key | -| **Default Inbox ID** | Inbox used when a tool call omits `inbox_id` | - -## Tool Actions - -| Action | Required args | Optional args | -|--------|---------------|---------------| -| `list_inboxes` | — | `limit` | -| `create_inbox` | — | `email`, `username`, `domain`, `display_name` | -| `send_email` | `inbox_id`, `to` | `subject`, `text`, `html`, `labels`, `attachments`, `thread_id` | -| `list_messages` | `inbox_id` | `limit` | -| `get_message` | `message_id` | — | - -### Attachments - -The `attachments` parameter is a JSON array of objects: - -```json -{ - "content": "", - "filename": "report.pdf", - "content_type": "application/pdf" -} -``` - -- `content` is required — use `base64 -w0` to encode files -- `filename` and `content_type` are optional -- Any file type is supported: PDF, images, documents, ZIP, audio, video, etc. - -### Thread Support - -Use `thread_id` with `send_email` to reply within an existing email thread: - -1. Get the `thread_id` from `list_messages` results -2. Pass it when calling `send_email` - -## Auto-Reply with Poller - -The plugin includes an internal loopback endpoint (`/api/plugins/agentmail/process_email`) that feeds incoming emails to Agent Zero for processing and returns the agent's reply. To automate this, you can set up a cron-based poller. - -### Poller Setup - -1. Place `agentmail_poll_once.py` in your work directory -2. Add a cron job to run it every minute: - -```bash -crontab -e -# Add: -* * * * * /opt/venv/bin/python /a0/usr/workdir/agentmail_poll_once.py >> /a0/usr/workdir/poll.log 2>&1 -``` - -The poller will: -- Check for new unread emails in the configured inbox -- Download and include text attachment content -- Send the email to Agent Zero for processing -- Automatically reply with the agent's response -- Attach any outbox files saved by the agent - -### Thread Continuity - -When an email arrives in an existing thread, the plugin reuses the same Agent Zero context. This means the agent **remembers the full conversation** from previous emails in that thread — no need to repeat context. - -- Thread → Context mapping is persisted in `agentmail_threads.json` -- If the server restarts and the context is lost, a new one is automatically created - -### Outbox Attachments - -The agent can save files to a per-context outbox directory, and they will be **automatically attached** to the reply email: - -1. The system prompt tells the agent the outbox path for the current context -2. The agent saves files there (e.g., translations, reports, generated content) -3. After the agent finishes, all outbox files are collected and attached to the reply -4. The outbox is cleaned up after successful send - -Example — the agent saves a translation: -```python -with open('/a0/usr/workdir/agentmail_outbox/abc123/translation.txt', 'w') as f: - f.write(translated_text) -``` - -### Safety Features - -- File lock prevents concurrent runs -- Email IDs are recorded before processing (prevents re-processing on crash) -- Maximum emails per cycle (default: 5) prevents runaway processing - -## Version History - -| Version | Changes | -|---------|---------| -| 1.2.0 | Thread continuity (context reuse across emails), outbox attachments, updated system prompt | -| 1.1.0 | Attachment support, thread_id for replies, attachment download in client | -| 1.0.0 | Initial release — send/receive emails, auto-reply poller | - -## Notes - -- The plugin is intended to run inside Agent Zero -- The internal processing endpoint is for loopback use only (127.0.0.1) -- The poller script is deployment-specific and lives outside the plugin directory - -## License - -MIT diff --git a/plugins/agentmail/plugin.yaml b/plugins/agentmail/plugin.yaml deleted file mode 100644 index e77b0bd..0000000 --- a/plugins/agentmail/plugin.yaml +++ /dev/null @@ -1,8 +0,0 @@ -name: agentmail -title: AgentMail Integration -description: Send and receive emails via the AgentMail API. -version: 1.2.0 -settings_sections: - - external -per_project_config: false -per_agent_config: true