AgentMail Skill: Agent-Owned Email Inboxes for Hermes Agent

AgentMail gives a Hermes Agent its own email inbox, separate from any human user's mailbox. You reach for this skill when the agent needs to send mail, receive replies, complete email OTP flows, or run inbound email loops on its own. It is an optional skill, installed on demand, and it is the right tool when the agent must own the address rather than borrow one from an existing IMAP or SMTP account.

What it does

With AgentMail, the agent gets a dedicated inbox it can fully control. It can send messages, read incoming mail, reply, forward, organize with labels, work with threads, and handle attachments. The skill also supports email-based one-time password (OTP) flows, which are common in signup and verification workflows. For inbound mail, you can choose between webhook or WebSocket delivery, so the agent does not have to poll for new messages.

The source is explicit about the interface hierarchy: use the agentmail CLI first. Use MCP only when the harness expects MCP tools, and use REST only when the CLI lacks a required operation. This keeps the workflow simple and consistent.

Before you start

You need two things in place before the skill works.

First, run commands through the terminal tool. That is the only supported way to execute the CLI.

Second, install the CLI globally with npm:

npm install -g agentmail-cli@latest

Then export your API key as an environment variable:

export AGENTMAIL_API_KEY="am_..."

If you do not have an API key yet, the source points to a signup reference that walks through self-signup and OTP verification. The skill supports Linux, macOS, and Windows, so platform is not a barrier.

How to run

The core command is agentmail inboxes list. Whenever another command or script needs IDs, use --format json so the output is machine-readable:

agentmail inboxes list --format json

This command also serves as a verification step after installation. If it returns your inboxes, the CLI and API key are working.

Working with core email operations

The source points to a core reference that covers inboxes, messages, threads, labels, and attachments. That is where you will find the detailed commands for sending, reading, replying, and forwarding. The skill is designed so that the CLI handles all of these operations, and the reference is the authoritative guide for each one.

Inbound delivery: webhooks and WebSockets

Polling is not always enough. When the agent needs to react to incoming mail promptly, the source recommends adding webhook or WebSocket delivery. Webhooks send events to a public HTTPS server, while WebSockets deliver events to a local agent process. The source is clear: add these only when polling is not enough, not as a default.

When not to use it

AgentMail is for agent-owned inboxes. It is not for a user's existing IMAP or SMTP mailbox. If the task requires acting on behalf of a human's personal or corporate email account, this skill is the wrong fit. Use it only when the agent needs an address it owns outright.

Limits and gotchas

The source lists several pitfalls worth internalizing before you build on this skill.

• Prefer the AGENTMAIL_API_KEY environment variable over passing --api-key on the command line. The environment variable keeps the key out of process listings and shell history.
• Never expose AGENTMAIL_API_KEY in prompts, logs, URLs, or committed files. Treat it as a secret at all times.
• Use stable client_id values for retried create operations. This makes operations idempotent, so a retry does not create duplicate resources.
• Prefer extracted_text or extracted_html for LLM input when present. These fields are already cleaned up for consumption, rather than raw MIME.
• React to message.received, not messages the agent sent. Otherwise the agent may loop on its own outbound mail.

Verification

After installation and configuration, confirm everything works with the same command you will use in practice:

agentmail inboxes list --format json

If this returns your inboxes, you are ready to build email workflows.

Related references

The source links to several references that expand on this skill. The hosted copy of the agent reference lives at AgentMail agent reference. The product landing page explains the service, and the console manages API keys and account settings. Full documentation is at Docs. The GitHub references cover signup, core operations, webhooks, websockets, and MCP integration.