Files

T

Haakam Aujla 14320d18df feat(skills): rewrite AgentMail optional skill CLI-first

Replaces the stale MCP-first AgentMail skill with CLI-first guidance:
self-signup + OTP verification, inbox/message/thread/label/attachment
flows, webhook and WebSocket delivery references, and MCP as an
alternative path. Declares AGENTMAIL_API_KEY (optional) so a stored key
reaches the sandboxed terminal while self-signup stays viable without
one.

Salvaged from PR #60811 — kept in optional-skills/ per the March 2026
decision that third-party-API-key skills are not bundled.

2026-08-27 07:09:26 -07:00

3.1 KiB

Raw Blame History

name, description, version, author, license, platforms, metadata, prerequisites, required_environment_variables

name

description

version

author

license

platforms

metadata

prerequisites

required_environment_variables

agentmail

Use when an agent needs AgentMail CLI email inboxes.

1.0.0

Haakam Aujla (Haakam21), AgentMail

MIT

linux

macos

windows

hermes

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:

npm install -g agentmail-cli@latest

Export an API key:

export AGENTMAIL_API_KEY="am_..."

No API key yet? Use signup.md.

How to Run

Use --format json whenever another command or script needs IDs.

agentmail inboxes list --format json

Quick Reference

AgentMail agent reference: hosted copy.
AgentMail: product landing page.
Console: API keys and account management.
Docs: full product documentation.
signup.md: self-signup and OTP verification.
core.md: inboxes, messages, threads, labels, attachments.
webhooks.md: events to a public HTTPS server.
websockets.md: events to a local agent process.
mcp.md: MCP integration.

Procedure

Install agentmail-cli@latest and verify agentmail inboxes list --format json.
If no API key is available, complete signup.md.
Use core.md for inbox, send, read, reply, forward, label, thread, and attachment flows.
Add webhooks.md or 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

agentmail inboxes list --format json

3.1 KiB Raw Blame History