From 2d189c81bd95e31a9845a9db9c749ebf115a9caa Mon Sep 17 00:00:00 2001 From: teknium1 <127238744+teknium1@users.noreply.github.com> Date: Wed, 15 Jul 2026 10:07:05 -0700 Subject: [PATCH] docs(skills): regen agentmail optional page + catalog row --- .../docs/reference/optional-skills-catalog.md | 2 +- .../skills/optional/email/email-agentmail.md | 159 +++++++----------- 2 files changed, 61 insertions(+), 100 deletions(-) diff --git a/website/docs/reference/optional-skills-catalog.md b/website/docs/reference/optional-skills-catalog.md index fea4afb4631..3f5268e6466 100644 --- a/website/docs/reference/optional-skills-catalog.md +++ b/website/docs/reference/optional-skills-catalog.md @@ -85,7 +85,7 @@ hermes skills uninstall | Skill | Description | |-------|-------------| -| [**agentmail**](/docs/user-guide/skills/optional/email/email-agentmail) | Give the agent its own dedicated email inbox via AgentMail. Send, receive, and manage email autonomously using agent-owned email addresses (e.g. hermes-agent@agentmail.to). | +| [**agentmail**](/docs/user-guide/skills/optional/email/email-agentmail) | Use when an agent needs AgentMail CLI email inboxes. | ## finance diff --git a/website/docs/user-guide/skills/optional/email/email-agentmail.md b/website/docs/user-guide/skills/optional/email/email-agentmail.md index 8f35ecf20ed..5fb31dba0fe 100644 --- a/website/docs/user-guide/skills/optional/email/email-agentmail.md +++ b/website/docs/user-guide/skills/optional/email/email-agentmail.md @@ -1,14 +1,14 @@ --- -title: "Agentmail — Give the agent its own dedicated email inbox via AgentMail" +title: "Agentmail — Use when an agent needs AgentMail CLI email inboxes" sidebar_label: "Agentmail" -description: "Give the agent its own dedicated email inbox via AgentMail" +description: "Use when an agent needs AgentMail CLI email inboxes" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Agentmail -Give the agent its own dedicated email inbox via AgentMail. Send, receive, and manage email autonomously using agent-owned email addresses (e.g. hermes-agent@agentmail.to). +Use when an agent needs AgentMail CLI email inboxes. ## Skill metadata @@ -17,8 +17,10 @@ Give the agent its own dedicated email inbox via AgentMail. Send, receive, and m | Source | Optional — install with `hermes skills install official/email/agentmail` | | Path | `optional-skills/email/agentmail` | | Version | `1.0.0` | +| Author | Haakam Aujla (Haakam21), AgentMail | +| License | MIT | | Platforms | linux, macos, windows | -| Tags | `email`, `communication`, `agentmail`, `mcp` | +| Tags | `Email`, `CLI`, `AgentMail`, `Communication` | ## Reference: full SKILL.md @@ -26,118 +28,77 @@ Give the agent its own dedicated email inbox via AgentMail. Send, receive, and m The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. ::: -# AgentMail — Agent-Owned Email Inboxes +# AgentMail Skill -## Requirements +AgentMail gives an agent its own email inbox for sending mail, receiving +replies, completing email OTP flows, and running inbound email loops. Use it for +agent-owned inboxes, not a user's existing IMAP/SMTP mailbox. -- **AgentMail API key** (required) — sign up at https://console.agentmail.to (free tier: 3 inboxes, 3,000 emails/month; paid plans from $20/mo) -- Node.js 18+ (for the MCP server) +Use the `agentmail` CLI first. Use MCP only when the harness expects MCP tools; +use REST only when the CLI is missing a required operation. ## When to Use -Use this skill when you need to: -- Give the agent its own dedicated email address -- Send emails autonomously on behalf of the agent -- Receive and read incoming emails -- Manage email threads and conversations -- Sign up for services or authenticate via email -- Communicate with other agents or humans via email -This is NOT for reading the user's personal email (use himalaya or Gmail for that). -AgentMail gives the agent its own identity and inbox. +- The agent needs an email address it owns. +- The task involves email OTP flows, replies, threads, labels, or attachments. +- The agent needs webhook or WebSocket delivery for inbound mail. -## Setup +## Prerequisites -### 1. Get an API Key -- Go to https://console.agentmail.to -- Create an account and generate an API key (starts with `am_`) +- Run commands through the `terminal` tool. +- Install the CLI: -### 2. Configure MCP Server -Add to `~/.hermes/config.yaml` (paste your actual key — MCP env vars are not expanded from .env): -```yaml -mcp_servers: - agentmail: - command: "npx" - args: ["-y", "agentmail-mcp"] - env: - AGENTMAIL_API_KEY: "am_your_key_here" -``` - -### 3. Restart Hermes ```bash -hermes +npm install -g agentmail-cli@latest ``` -All 11 AgentMail tools are now available automatically. -## Available Tools (via MCP) +- Export an API key: -| Tool | Description | -|------|-------------| -| `list_inboxes` | List all agent inboxes | -| `get_inbox` | Get details of a specific inbox | -| `create_inbox` | Create a new inbox (gets a real email address) | -| `delete_inbox` | Delete an inbox | -| `list_threads` | List email threads in an inbox | -| `get_thread` | Get a specific email thread | -| `send_message` | Send a new email | -| `reply_to_message` | Reply to an existing email | -| `forward_message` | Forward an email | -| `update_message` | Update message labels/status | -| `get_attachment` | Download an email attachment | +```bash +export AGENTMAIL_API_KEY="am_..." +``` + +No API key yet? Use [signup.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/signup.md). + +## How to Run + +Use `--format json` whenever another command or script needs IDs. + +```bash +agentmail inboxes list --format json +``` + +## Quick Reference + +- [AgentMail agent reference](https://agentmail.md): hosted copy. +- [AgentMail](https://agentmail.to): product landing page. +- [Console](https://console.agentmail.to): API keys and account management. +- [Docs](https://docs.agentmail.to): full product documentation. +- [signup.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/signup.md): self-signup and OTP verification. +- [core.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/core.md): inboxes, messages, threads, labels, attachments. +- [webhooks.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/webhooks.md): events to a public HTTPS server. +- [websockets.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/websockets.md): events to a local agent process. +- [mcp.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/mcp.md): MCP integration. ## Procedure -### Create an inbox and send an email -1. Create a dedicated inbox: - - Use `create_inbox` with a username (e.g. `hermes-agent`) - - The agent gets address: `hermes-agent@agentmail.to` -2. Send an email: - - Use `send_message` with `inbox_id`, `to`, `subject`, `text` -3. Check for replies: - - Use `list_threads` to see incoming conversations - - Use `get_thread` to read a specific thread - -### Check incoming email -1. Use `list_inboxes` to find your inbox ID -2. Use `list_threads` with the inbox ID to see conversations -3. Use `get_thread` to read a thread and its messages - -### Reply to an email -1. Get the thread with `get_thread` -2. Use `reply_to_message` with the message ID and your reply text - -## Example Workflows - -**Sign up for a service:** -``` -1. create_inbox (username: "signup-bot") -2. Use the inbox address to register on the service -3. list_threads to check for verification email -4. get_thread to read the verification code -``` - -**Agent-to-human outreach:** -``` -1. create_inbox (username: "hermes-outreach") -2. send_message (to: user@example.com, subject: "Hello", text: "...") -3. list_threads to check for replies -``` +1. Install `agentmail-cli@latest` and verify `agentmail inboxes list --format json`. +2. If no API key is available, complete [signup.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/signup.md). +3. Use [core.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/core.md) for inbox, send, read, reply, forward, + label, thread, and attachment flows. +4. Add [webhooks.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/webhooks.md) or + [websockets.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/websockets.md) only when polling is not enough. ## Pitfalls -- Free tier limited to 3 inboxes and 3,000 emails/month -- Emails come from `@agentmail.to` domain on free tier (custom domains on paid plans) -- Node.js (18+) is required for the MCP server (`npx -y agentmail-mcp`) -- The `mcp` Python package must be installed: `pip install mcp` -- Real-time inbound email (webhooks) requires a public server — use `list_threads` polling via cronjob instead for personal use + +- Prefer `AGENTMAIL_API_KEY` over `--api-key`. +- Never expose `AGENTMAIL_API_KEY` in prompts, logs, URLs, or committed files. +- Use stable `client_id` values for retried create operations. +- Prefer `extracted_text` or `extracted_html` for LLM input when present. +- React to `message.received`, not messages the agent sent. ## Verification -After setup, test with: -``` -hermes --toolsets mcp -q "Create an AgentMail inbox called test-agent and tell me its email address" -``` -You should see the new inbox address returned. -## References -- AgentMail docs: https://docs.agentmail.to/ -- AgentMail console: https://console.agentmail.to -- AgentMail MCP repo: https://github.com/agentmail-to/agentmail-mcp -- Pricing: https://www.agentmail.to/pricing +```bash +agentmail inboxes list --format json +```