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

Security Scan

The skill's requirements and runtime instructions are internally consistent with an email-management CLI: it needs node, an agentmail binary (installed from an npm package), and an AgentMail API key — all of which are appropriate for the described purpose.

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.

Assessment

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.

Email management for AI agents via the AgentMail API.

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

Prerequisites

Required:

• Node.js >= 20.0.0
• AgentMail API key from agentmail.to

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 <inbox-id>

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

Thread Management

# List threads in inbox
agentmail threads list <inbox-id>

# List with options
agentmail threads list <inbox-id> --limit 10

# Filter by labels
agentmail threads list <inbox-id> --labels '["unread"]'

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

# Get thread details (includes all messages)
agentmail threads get <inbox-id> <thread-id>

Send Messages

# Send a simple email
agentmail messages send <inbox-id> \
  --to [e-mail] \
  --subject "Hello" \
  --text "Email body here"

# Send to multiple recipients
agentmail messages send <inbox-id> \
  --to [e-mail] \
  --to [e-mail] \
  --subject "Team Update" \
  --text "Hello team..."

# Send with CC and BCC
agentmail messages send <inbox-id> \
  --to [e-mail] \
  --cc [e-mail] \
  --bcc [e-mail] \
  --subject "Important" \
  --text "Please review..."

# Send HTML email
agentmail messages send <inbox-id> \
  --to [e-mail] \
  --subject "Newsletter" \
  --html "<h1>Hello</h1><p>HTML content</p>"

# Send with labels
agentmail messages send <inbox-id> \
  --to [e-mail] \
  --subject "Outreach" \
  --text "Hello..." \
  --labels '["campaign","outbound"]'

Reply & Forward

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

# Reply with HTML
agentmail messages reply <inbox-id> <message-id> \
  --html "<p>Thank you!</p>"

# Reply all
agentmail messages reply <inbox-id> <message-id> \
  --text "Replying to everyone..." \
  --reply-all

# Forward a message
agentmail messages forward <inbox-id> <message-id> \
  --to [e-mail] \
  --text "FYI - see below"

# Forward to multiple
agentmail messages forward <inbox-id> <message-id> \
  --to [e-mail] \
  --cc [e-mail] \
  --subject "Fwd: Customer Inquiry" \
  --text "Please review"

Labels & Organization

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

# Remove labels
agentmail messages update <inbox-id> <message-id> \
  --remove-labels '["unread"]'

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

Attachments

# Get attachment details and download URL
agentmail attachments get <thread-id> <attachment-id>

Available Commands

Command	Description
inboxes list	List all inboxes
inboxes get <id>	Get inbox details
inboxes create	Create new inbox
inboxes delete <id>	Delete inbox
threads list <inbox-id>	List threads
threads get <inbox-id> <thread-id>	Get thread with messages
messages send <inbox-id>	Send new email
messages reply <inbox-id> <msg-id>	Reply to email
messages forward <inbox-id> <msg-id>	Forward email
messages update <inbox-id> <msg-id>	Update labels
attachments get <thread-id> <att-id>	Get attachment

Command Options Reference

inboxes list

• -l, --limit <n> - Max items (default: 10)
• --page-token <token> - Pagination token

inboxes create

• -u, --username <name> - Email username
• -d, --domain <domain> - Email domain
• -n, --display-name <name> - Display name

threads list

• -l, --limit <n> - Max items (default: 10)
• --page-token <token> - Pagination token
• --labels <json> - Filter by labels (JSON array)
• --before <datetime> - Before date (ISO 8601)
• --after <datetime> - After date (ISO 8601)

messages send

• --to <email> - Recipient (repeatable)
• --cc <email> - CC recipient (repeatable)
• --bcc <email> - BCC recipient (repeatable)
• -s, --subject <text> - Subject line
• -t, --text <body> - Plain text body
• --html <body> - HTML body
• --labels <json> - Labels (JSON array)

messages reply

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

messages forward

• --to <email> - Recipient (repeatable)
• --cc <email> - CC recipient (repeatable)
• --bcc <email> - BCC recipient (repeatable)
• -s, --subject <text> - Subject line
• -t, --text <body> - Plain text body
• --html <body> - HTML body
• --labels <json> - Labels (JSON array)

messages update

• --add-labels <json> - Labels to add (JSON array)
• --remove-labels <json> - Labels to remove (JSON array)

Common Workflows

Check for New Emails

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

Process and Archive Email

# 1. Get thread
agentmail threads get <inbox-id> <thread-id>

# 2. Process content (your logic)

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

Auto-Reply Workflow

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

# 2. Get thread details
agentmail threads get <inbox-id> <thread-id>

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

# 4. Update labels
agentmail messages update <inbox-id> <message-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 <new-inbox-id> \
  --to [e-mail] \
  --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:<inbox-id> \
  to:'["[e-mail]"]' \
  subject:"Hello" \
  text:"Body"

Links

• API Documentation: https://docs.agentmail.to
• Get API Key: https://agentmail.to
• MCP Server: https://github.com/agentmail-to/agentmail-mcp
• Node SDK: https://github.com/agentmail-to/agentmail-node