AgentMail MCP CLI

v1.0.3

Manage AI agent email accounts via AgentMail API. Create inboxes, send/receive/reply to emails, manage threads and attachments. Use for "email", "agentmail",...

1· 425· 4 versions· 0 current· 0 all-time· Updated 8h ago· MIT-0

byFlorian Heiwig@flohiwg

Security Scans

VirusTotalBenign ClawScanBenign Static analysisBenign

Install

openclaw skills install 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	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 prospect@example.com \
  --subject "Introduction" \
  --text "Hello! I wanted to reach out..."

Error Handling

If commands fail, check:

API Key: Ensure AGENTMAIL_API_KEY is set
IDs: Verify inbox/thread/message IDs exist
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"

AgentMail MCP CLI

Security Scans

Install

AgentMail MCP CLI

Prerequisites

Authentication

Quick Reference

Inbox Management

Thread Management

Send Messages

Reply & Forward

Labels & Organization

Attachments

Available Commands

Command Options Reference

inboxes list

inboxes create

threads list

messages send

messages reply

messages forward

messages update

Common Workflows

Check for New Emails

Process and Archive Email

Auto-Reply Workflow

Create Inbox and Send First Email

Error Handling

Alternative: MCPorter Syntax

Links

Version tags

Runtime requirements

Install