---

name: 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", "inbox", "send email", "reply email", "forward email", "email agent", "mail api", "agent inbox". version: 1.0.0 metadata: openclaw: requires: env: - AGENTMAIL_API_KEY bins: - node - agentmail primaryEnv: AGENTMAIL_API_KEY install: - kind: node package: openclaw-agentmail-cli bins: - agentmail homepage: https://agentmail.to docs: https://docs.agentmail.to repository: https://github.com/FloHiwg/agentmail-cli

---

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:

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 
Delete an inbox (destructive!)
agentmail inboxes delete 

Thread Management

# List threads in inbox
agentmail threads list 
List with options
agentmail threads list  --limit 10
Filter by labels
agentmail threads list  --labels '["unread"]'
Filter by date
agentmail threads list  --after "2024-01-01" --before "2024-12-31"
Get thread details (includes all messages)
agentmail threads get  

Send Messages

# Send a simple email
agentmail messages send  \
  --to user@example.com \
  --subject "Hello" \
  --text "Email body here"
Send to multiple recipients
agentmail messages send  \
  --to user1@example.com \
  --to user2@example.com \
  --subject "Team Update" \
  --text "Hello team..."
Send with CC and BCC
agentmail messages send  \
  --to primary@example.com \
  --cc copy@example.com \
  --bcc hidden@example.com \
  --subject "Important" \
  --text "Please review..."
Send HTML email
agentmail messages send  \
  --to user@example.com \
  --subject "Newsletter" \
  --html "
Hello
HTML content
"
Send with labels
agentmail messages send  \
  --to user@example.com \
  --subject "Outreach" \
  --text "Hello..." \
  --labels '["campaign","outbound"]'

Reply & Forward

# Reply to a message
agentmail messages reply   \
  --text "Thank you for your email."
Reply with HTML
agentmail messages reply   \
  --html "
Thank you!
"
Reply all
agentmail messages reply   \
  --text "Replying to everyone..." \
  --reply-all
Forward a message
agentmail messages forward   \
  --to forward-to@example.com \
  --text "FYI - see below"
Forward to multiple
agentmail messages forward   \
  --to team@example.com \
  --cc manager@example.com \
  --subject "Fwd: Customer Inquiry" \
  --text "Please review"

Labels & Organization

# Add labels to a message
agentmail messages update   \
  --add-labels '["important","needs-review"]'
Remove labels
agentmail messages update   \
  --remove-labels '["unread"]'
Add and remove simultaneously
agentmail messages update   \
  --add-labels '["processed"]' \
  --remove-labels '["unread","pending"]'

Attachments

# Get attachment details and download URL
agentmail attachments get  

Available Commands

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

Command Options Reference

inboxes list

-l, --limit - Max items (default: 10)

--page-token - Pagination token

inboxes create

-u, --username - Email username

-d, --domain - Email domain

-n, --display-name - Display name

threads list

-l, --limit - Max items (default: 10)

--page-token - Pagination token

--labels - Filter by labels (JSON array)

--before - Before date (ISO 8601)

--after - After date (ISO 8601)

messages send

--to - Recipient (repeatable)

--cc - CC recipient (repeatable)

--bcc - BCC recipient (repeatable)

-s, --subject - Subject line

-t, --text - Plain text body

--html - HTML body

--labels - Labels (JSON array)

messages reply

-t, --text - Plain text body

--html - HTML body

--reply-all - Reply to all recipients

--labels - Labels (JSON array)

messages forward

--to - Recipient (repeatable)

--cc - CC recipient (repeatable)

--bcc - BCC recipient (repeatable)

-s, --subject - Subject line

-t, --text - Plain text body

--html - HTML body

--labels - Labels (JSON array)

messages update

--add-labels - Labels to add (JSON array)

--remove-labels - Labels to remove (JSON array)

Common Workflows

Check for New Emails

# List unread threads
agentmail threads list  --labels '["unread"]' --limit 20

Process and Archive Email

# 1. Get thread
agentmail threads get  
2. Process content (your logic)
3. Mark as processed
agentmail messages update   \
  --add-labels '["processed"]' \
  --remove-labels '["unread"]'

Auto-Reply Workflow

# 1. Check for emails needing reply
agentmail threads list  --labels '["needs-reply"]'
2. Get thread details
agentmail threads get  
3. Send reply
agentmail messages reply   \
  --text "Thank you for reaching out. We will respond within 24 hours."
4. Update labels
agentmail messages update   \
  --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  \
  --to prospect@example.com \
  --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: \
  to:'["user@example.com"]' \
  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

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.