Agentmail MCP 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 <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 user@example.com \
  --subject "Hello" \
  --text "Email body here"

# Send to multiple recipients
agentmail messages send <inbox-id> \
  --to user1@example.com \
  --to user2@example.com \
  --subject "Team Update" \
  --text "Hello team..."

# Send with CC and BCC
agentmail messages send <inbox-id> \
  --to primary@example.com \
  --cc copy@example.com \
  --bcc hidden@example.com \
  --subject "Important" \
  --text "Please review..."

# Send HTML email
agentmail messages send <inbox-id> \
  --to user@example.com \
  --subject "Newsletter" \
  --html "<h1>Hello</h1><p>HTML content</p>"

# Send with labels
agentmail messages send <inbox-id> \
  --to user@example.com \
  --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 forward-to@example.com \
  --text "FYI - see below"

# Forward to multiple
agentmail messages forward <inbox-id> <message-id> \
  --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 <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 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 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:<inbox-id> \
  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