agentmail

1---2name: agentmail3description: Use when an agent needs AgentMail CLI email inboxes.4version: 1.0.05author: Haakam Aujla (Haakam21), AgentMail6license: MIT7platforms: [linux, macos, windows]8metadata:9  hermes:10    tags: [Email, CLI, AgentMail, Communication]11    homepage: https://agentmail.to12prerequisites:13  commands: [agentmail]14required_environment_variables:15  - name: AGENTMAIL_API_KEY16    prompt: AgentMail API key (starts with am_)17    help: "Create one at https://console.agentmail.to — or run the CLI self-signup flow in references/signup.md to obtain a key without one."18    required_for: "authenticating the agentmail CLI; not needed before self-signup"19    optional: true20---21 22# AgentMail Skill23 24AgentMail gives an agent its own email inbox for sending mail, receiving25replies, completing email OTP flows, and running inbound email loops. Use it for26agent-owned inboxes, not a user's existing IMAP/SMTP mailbox.27 28Use the `agentmail` CLI first. Use MCP only when the harness expects MCP tools;29use REST only when the CLI is missing a required operation.30 31## When to Use32 33- The agent needs an email address it owns.34- The task involves email OTP flows, replies, threads, labels, or attachments.35- The agent needs webhook or WebSocket delivery for inbound mail.36 37## Prerequisites38 39- Run commands through the `terminal` tool.40- Install the CLI:41 42```bash43npm install -g agentmail-cli@latest44```45 46- Export an API key:47 48```bash49export AGENTMAIL_API_KEY="am_..."50```51 52No API key yet? Use [signup.md](references/signup.md).53 54## How to Run55 56Use `--format json` whenever another command or script needs IDs.57 58```bash59agentmail inboxes list --format json60```61 62## Quick Reference63 64- [AgentMail agent reference](https://agentmail.md): hosted copy.65- [AgentMail](https://agentmail.to): product landing page.66- [Console](https://console.agentmail.to): API keys and account management.67- [Docs](https://docs.agentmail.to): full product documentation.68- [signup.md](references/signup.md): self-signup and OTP verification.69- [core.md](references/core.md): inboxes, messages, threads, labels, attachments.70- [webhooks.md](references/webhooks.md): events to a public HTTPS server.71- [websockets.md](references/websockets.md): events to a local agent process.72- [mcp.md](references/mcp.md): MCP integration.73 74## Procedure75 761. Install `agentmail-cli@latest` and verify `agentmail inboxes list --format json`.772. If no API key is available, complete [signup.md](references/signup.md).783. Use [core.md](references/core.md) for inbox, send, read, reply, forward,79   label, thread, and attachment flows.804. Add [webhooks.md](references/webhooks.md) or81   [websockets.md](references/websockets.md) only when polling is not enough.82 83## Pitfalls84 85- Prefer `AGENTMAIL_API_KEY` over `--api-key`.86- Never expose `AGENTMAIL_API_KEY` in prompts, logs, URLs, or committed files.87- Use stable `client_id` values for retried create operations.88- Prefer `extracted_text` or `extracted_html` for LLM input when present.89- React to `message.received`, not messages the agent sent.90 91## Verification92 93```bash94agentmail inboxes list --format json95```96