---
name: aivrar-agentmail
description: "Use when an agent needs AgentMail CLI email inboxes."
license: "MIT"
metadata:
  decimalai-skill-id: "2bd83841-3793-473b-bd62-ff679cf64c9c"
  decimalai-version-id: "d8f61e7c-f2f7-4c8d-9fdf-ea3f2861e195"
  decimalai-version: "1"
  decimalai-body-sha256: "1672a6f90b635b6f1fe6d2d6f47db9bf7d5069715107525388c68794552b892e"
  decimalai-name: "aivrar/agentmail"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "agent-tooling"
  decimalai-source: "https://app.decimal.ai/s/aivrar-agentmail@1/SKILL.md"
---
# AgentMail Skill

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.

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

- 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.

## Prerequisites

- Run commands through the `terminal` tool.
- Install the CLI:

```bash
npm install -g agentmail-cli@latest
```

- Export an API key:

```bash
export AGENTMAIL_API_KEY="am_..."
```

No API key yet? Use [signup.md](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](references/signup.md): self-signup and OTP verification.
- [core.md](references/core.md): inboxes, messages, threads, labels, attachments.
- [webhooks.md](references/webhooks.md): events to a public HTTPS server.
- [websockets.md](references/websockets.md): events to a local agent process.
- [mcp.md](references/mcp.md): MCP integration.

## Procedure

1. Install `agentmail-cli@latest` and verify `agentmail inboxes list --format json`.
2. If no API key is available, complete [signup.md](references/signup.md).
3. Use [core.md](references/core.md) for inbox, send, read, reply, forward,
   label, thread, and attachment flows.
4. Add [webhooks.md](references/webhooks.md) or
   [websockets.md](references/websockets.md) only when polling is not enough.

## Pitfalls

- 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

```bash
agentmail inboxes list --format json
```