← Back to Skills Marketplace
flohiwg

AgentMail MCP CLI

by Florian Heiwig · GitHub ↗ · v1.0.3
cross-platform ✓ Security Clean
419
Downloads
1
Stars
0
Active Installs
4
Versions
Install in OpenClaw
/install agentmail-mcp-cli
Description
Manage AI agent email accounts via AgentMail API. Create inboxes, send/receive/reply to emails, manage threads and attachments. Use for "email", "agentmail",...
README (SKILL.md)

AgentMail MCP CLI

Email management for AI agents via the AgentMail API.

Documentation: https://docs.agentmail.to Get API Key: https://agentmail.to

Prerequisites

Required:

Installation:

npm install -g openclaw-agentmail-cli

This installs the agentmail command globally.

Authentication

Set your API key (get one from agentmail.to):

# Option 1: Environment variable (recommended)
export AGENTMAIL_API_KEY="your_api_key"
agentmail inboxes list

# Option 2: CLI parameter
agentmail --api-key "your_api_key" inboxes list

Quick Reference

Inbox Management

# List all inboxes
agentmail inboxes list

# List with limit
agentmail inboxes list --limit 5

# Create a new inbox
agentmail inboxes create --display-name "My Agent"

# Create with username and domain
agentmail inboxes create --username myagent --domain agentmail.to --display-name "My Agent"

# Get inbox details
agentmail inboxes get \x3Cinbox-id>

# Delete an inbox (destructive!)
agentmail inboxes delete \x3Cinbox-id>

Thread Management

# List threads in inbox
agentmail threads list \x3Cinbox-id>

# List with options
agentmail threads list \x3Cinbox-id> --limit 10

# Filter by labels
agentmail threads list \x3Cinbox-id> --labels '["unread"]'

# Filter by date
agentmail threads list \x3Cinbox-id> --after "2024-01-01" --before "2024-12-31"

# Get thread details (includes all messages)
agentmail threads get \x3Cinbox-id> \x3Cthread-id>

Send Messages

# Send a simple email
agentmail messages send \x3Cinbox-id> \
  --to [email protected] \
  --subject "Hello" \
  --text "Email body here"

# Send to multiple recipients
agentmail messages send \x3Cinbox-id> \
  --to [email protected] \
  --to [email protected] \
  --subject "Team Update" \
  --text "Hello team..."

# Send with CC and BCC
agentmail messages send \x3Cinbox-id> \
  --to [email protected] \
  --cc [email protected] \
  --bcc [email protected] \
  --subject "Important" \
  --text "Please review..."

# Send HTML email
agentmail messages send \x3Cinbox-id> \
  --to [email protected] \
  --subject "Newsletter" \
  --html "\x3Ch1>Hello\x3C/h1>\x3Cp>HTML content\x3C/p>"

# Send with labels
agentmail messages send \x3Cinbox-id> \
  --to [email protected] \
  --subject "Outreach" \
  --text "Hello..." \
  --labels '["campaign","outbound"]'

Reply & Forward

# Reply to a message
agentmail messages reply \x3Cinbox-id> \x3Cmessage-id> \
  --text "Thank you for your email."

# Reply with HTML
agentmail messages reply \x3Cinbox-id> \x3Cmessage-id> \
  --html "\x3Cp>Thank you!\x3C/p>"

# Reply all
agentmail messages reply \x3Cinbox-id> \x3Cmessage-id> \
  --text "Replying to everyone..." \
  --reply-all

# Forward a message
agentmail messages forward \x3Cinbox-id> \x3Cmessage-id> \
  --to [email protected] \
  --text "FYI - see below"

# Forward to multiple
agentmail messages forward \x3Cinbox-id> \x3Cmessage-id> \
  --to [email protected] \
  --cc [email protected] \
  --subject "Fwd: Customer Inquiry" \
  --text "Please review"

Labels & Organization

# Add labels to a message
agentmail messages update \x3Cinbox-id> \x3Cmessage-id> \
  --add-labels '["important","needs-review"]'

# Remove labels
agentmail messages update \x3Cinbox-id> \x3Cmessage-id> \
  --remove-labels '["unread"]'

# Add and remove simultaneously
agentmail messages update \x3Cinbox-id> \x3Cmessage-id> \
  --add-labels '["processed"]' \
  --remove-labels '["unread","pending"]'

Attachments

# Get attachment details and download URL
agentmail attachments get \x3Cthread-id> \x3Cattachment-id>

Available Commands

Command Description
inboxes list List all inboxes
inboxes get \x3Cid> Get inbox details
inboxes create Create new inbox
inboxes delete \x3Cid> Delete inbox
threads list \x3Cinbox-id> List threads
threads get \x3Cinbox-id> \x3Cthread-id> Get thread with messages
messages send \x3Cinbox-id> Send new email
messages reply \x3Cinbox-id> \x3Cmsg-id> Reply to email
messages forward \x3Cinbox-id> \x3Cmsg-id> Forward email
messages update \x3Cinbox-id> \x3Cmsg-id> Update labels
attachments get \x3Cthread-id> \x3Catt-id> Get attachment

Command Options Reference

inboxes list

  • -l, --limit \x3Cn> - Max items (default: 10)
  • --page-token \x3Ctoken> - Pagination token

inboxes create

  • -u, --username \x3Cname> - Email username
  • -d, --domain \x3Cdomain> - Email domain
  • -n, --display-name \x3Cname> - Display name

threads list

  • -l, --limit \x3Cn> - Max items (default: 10)
  • --page-token \x3Ctoken> - Pagination token
  • --labels \x3Cjson> - Filter by labels (JSON array)
  • --before \x3Cdatetime> - Before date (ISO 8601)
  • --after \x3Cdatetime> - After date (ISO 8601)

messages send

  • --to \x3Cemail> - Recipient (repeatable)
  • --cc \x3Cemail> - CC recipient (repeatable)
  • --bcc \x3Cemail> - BCC recipient (repeatable)
  • -s, --subject \x3Ctext> - Subject line
  • -t, --text \x3Cbody> - Plain text body
  • --html \x3Cbody> - HTML body
  • --labels \x3Cjson> - Labels (JSON array)

messages reply

  • -t, --text \x3Cbody> - Plain text body
  • --html \x3Cbody> - HTML body
  • --reply-all - Reply to all recipients
  • --labels \x3Cjson> - Labels (JSON array)

messages forward

  • --to \x3Cemail> - Recipient (repeatable)
  • --cc \x3Cemail> - CC recipient (repeatable)
  • --bcc \x3Cemail> - BCC recipient (repeatable)
  • -s, --subject \x3Ctext> - Subject line
  • -t, --text \x3Cbody> - Plain text body
  • --html \x3Cbody> - HTML body
  • --labels \x3Cjson> - Labels (JSON array)

messages update

  • --add-labels \x3Cjson> - Labels to add (JSON array)
  • --remove-labels \x3Cjson> - Labels to remove (JSON array)

Common Workflows

Check for New Emails

# List unread threads
agentmail threads list \x3Cinbox-id> --labels '["unread"]' --limit 20

Process and Archive Email

# 1. Get thread
agentmail threads get \x3Cinbox-id> \x3Cthread-id>

# 2. Process content (your logic)

# 3. Mark as processed
agentmail messages update \x3Cinbox-id> \x3Cmessage-id> \
  --add-labels '["processed"]' \
  --remove-labels '["unread"]'

Auto-Reply Workflow

# 1. Check for emails needing reply
agentmail threads list \x3Cinbox-id> --labels '["needs-reply"]'

# 2. Get thread details
agentmail threads get \x3Cinbox-id> \x3Cthread-id>

# 3. Send reply
agentmail messages reply \x3Cinbox-id> \x3Cmessage-id> \
  --text "Thank you for reaching out. We will respond within 24 hours."

# 4. Update labels
agentmail messages update \x3Cinbox-id> \x3Cmessage-id> \
  --add-labels '["auto-replied"]' \
  --remove-labels '["needs-reply","unread"]'

Create Inbox and Send First Email

# 1. Create inbox
agentmail inboxes create --display-name "Sales Bot"
# Note the inboxId from response

# 2. Send email
agentmail messages send \x3Cnew-inbox-id> \
  --to [email protected] \
  --subject "Introduction" \
  --text "Hello! I wanted to reach out..."

Error Handling

If commands fail, check:

  1. API Key: Ensure AGENTMAIL_API_KEY is set
  2. IDs: Verify inbox/thread/message IDs exist
  3. JSON: Use proper JSON for array options: '["value"]'

Alternative: MCPorter Syntax

If the MCP compatibility is restored, you can also use MCPorter:

# List inboxes
npx mcporter call agentmail.list_inboxes

# Send message
npx mcporter call agentmail.send_message \
  inboxId:\x3Cinbox-id> \
  to:'["[email protected]"]' \
  subject:"Hello" \
  text:"Body"

Links

Usage Guidance
This skill appears coherent for managing AgentMail accounts, but before installing: 1) Verify the npm package 'openclaw-agentmail-cli' and its publisher on the npm registry and inspect the GitHub repository to ensure it matches expectations. 2) Limit the AGENTMAIL_API_KEY scope and use an ephemeral or low-privilege key if possible. 3) Be aware the skill (and the agent using it) will have access to full email contents and attachments; avoid granting keys that expose unrelated accounts or data. 4) If you want to reduce risk, run the CLI in an isolated environment/container and avoid giving the agent autonomous access to sensitive inboxes until you trust the package. 5) If you need higher assurance, request the package's signed releases or a reproducible build from the maintainer.
Capability Analysis
Type: OpenClaw Skill Name: agentmail-mcp-cli Version: 1.0.3 The skill bundle defines an OpenClaw agent skill for managing email accounts via the AgentMail API. The `SKILL.md` file provides clear instructions for installation (`npm install -g openclaw-agentmail-cli`) and usage of the `agentmail` CLI tool, which interacts with the `agentmail.to` service. All commands and instructions are directly aligned with the stated purpose of email management (creating inboxes, sending/receiving emails, managing threads and attachments). There is no evidence of prompt injection attempts against the agent, no instructions for data exfiltration, persistence, or other malicious activities. The required network and file access capabilities are inherent to its function as an email client. While the `npm` installation introduces a supply chain risk if the `openclaw-agentmail-cli` package itself were malicious, the skill bundle's content and instructions do not exhibit malicious intent.
Capability Assessment
✓ Purpose & Capability
The name/description (manage AgentMail inboxes, send/receive/reply, attachments) matches the declared requirements: a node-based CLI 'agentmail' and an AGENTMAIL_API_KEY. Asking for an API key and the CLI binary is proportionate to the skill's stated purpose.
✓ Instruction Scope
SKILL.md contains only CLI usage instructions for the agentmail tool (inboxes, threads, messages, attachments). It does not instruct the agent to read unrelated files, look up unrelated credentials, or send data to endpoints beyond AgentMail (docs/homepage point to agentmail.to). Note: the skill will access email contents and attachments by design — that is expected but has privacy implications.
ℹ Install Mechanism
Install uses an npm package (openclaw-agentmail-cli) which is a common and expected distribution method for a Node CLI. npm installs are moderate risk compared with curated package managers because packages can contain arbitrary code; verify the package's publisher and contents before installing in sensitive environments.
✓ Credentials
Only the AGENTMAIL_API_KEY is required and declared as the primary credential. That single API key is appropriate for interacting with the AgentMail API and is proportionate to the skill's capabilities.
✓ Persistence & Privilege
The skill does not request always:true, does not modify other skills' config, and declares no system config paths. It can be invoked autonomously (platform default), which increases blast radius but is not unusual for skills and is not by itself a coherence problem.
How to Use
  1. Make sure OpenClaw is installed (local or Docker)
  2. Run the install command in chat: /install agentmail-mcp-cli
  3. After installation, invoke the skill by name or use /agentmail-mcp-cli
  4. Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.3
- Updated SKILL.md to revise and restructure the metadata format. - Moved and expanded environment variable, binary, and install details under a new `openclaw` metadata section. - Set the homepage, documentation, and repository links inside the new metadata block. - Clarified the version field at the root of the file. - No changes to core usage instructions, but internal documentation structure is now more consistent for OpenClaw/MCP compatibility.
v1.0.2
- Added repository link to metadata for improved reference and transparency. - Updated binaries requirement to only include "node" and "agentmail". - Defined a structured install block for clearer installation instructions. - Removed npx usage from instructions; now only supports global installation via npm. - Minor documentation clarifications throughout SKILL.md.
v1.0.1
- Skill name updated to `agentmail-mcp-cli` for clarity. - npm package changed to `openclaw-agentmail-cli`. - Node.js 20+ is now required. - Usage instructions updated to use `openclaw-agentmail-cli` instead of `agentmail-cli`. - Clarified required environment variables (`AGENTMAIL_API_KEY`) and bin dependencies (`node`, `npx`). - Skill documentation and metadata now reflect new CLI name and requirements.
v1.0.0
Initial release of AgentMail CLI for managing AI agent email accounts. - Manage inboxes: create, list, get details, and delete. - Send, receive, reply, and forward emails, with optional CC, BCC, HTML, and labels. - Organize and update email threads with labels and filtering options. - Handle attachments: retrieve details and download URLs. - Detailed CLI usage instructions and workflow examples included. - Supports API Key authentication through environment variable or CLI flag.
Metadata
Slug agentmail-mcp-cli
Version 1.0.3
License —
All-time Installs 0
Active Installs 0
Total Versions 4
Frequently Asked Questions

What is AgentMail MCP CLI?

Manage AI agent email accounts via AgentMail API. Create inboxes, send/receive/reply to emails, manage threads and attachments. Use for "email", "agentmail",... It is an AI Agent Skill for Claude Code / OpenClaw, with 419 downloads so far.

How do I install AgentMail MCP CLI?

Run "/install agentmail-mcp-cli" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is AgentMail MCP CLI free?

Yes, AgentMail MCP CLI is completely free (open-source). You can download, install and use it at no cost.

Which platforms does AgentMail MCP CLI support?

AgentMail MCP CLI is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created AgentMail MCP CLI?

It is built and maintained by Florian Heiwig (@flohiwg); the current version is v1.0.3.

More Skills
self-improving agent
Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Clau...
⬇ 463283 · by pskoett
Skill Vetter
Security-first skill vetting for AI agents. Use before installing any skill from ClawdHub, GitHub, or other sources. Checks for red flags, permission scope, and suspicious patterns.
⬇ 259410 · by spclaudehome
Polymarket
Query Polymarket prediction markets. Check odds, find trending markets, search events, track price movements.
⬇ 232503 · by joelchance
Self-Improving + Proactive Agent
Self-reflection + Self-criticism + Self-learning + Self-organizing memory. Agent evaluates its own work, catches mistakes, and improves permanently. Use when...
⬇ 200423 · by ivangdavila
Github
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
⬇ 191113 · by steipete
ontology
Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linkin...
⬇ 190156 · by oswalpalash

💬 Comments