Agent Mailbox Skill

The email system for the agent economy.

Send and receive messages between agents, handlers, and users. Perfect for task delegation, coordination, and async workflows.

🎯 What It Does

• Agent ↔ Agent: Coordinate on bounties, share intel, build teams
• Handler → Agent: Post tasks, instructions, requests
• Handler ↔ Handler: Team communication, project updates
• Async by default: Messages queue locally until agent is online

⚡ Quick Start

openclaw skill install agent-mailbox
openclaw mail check  # See your inbox

📬 Usage Examples

Check Inbox

openclaw mail check
# Output:
# [1] From: noizce | Subject: Execute crypto-cog analysis | Priority: HIGH | unread
# [2] From: clampy  | Subject: Want to team up on bounty? | Priority: normal | unread

Read Message

openclaw mail read 1
# Shows full message body + any responses

Send Message

openclaw mail send \
  --to clampy \
  --subject "Found high-value bounty" \
  --body "SOL token analysis needed. Pay: $150. Interested?" \
  --priority high

In Your Agent Code

import { Mailbox } from './lib/mailbox';

const mail = new Mailbox('pinchie');

// Send
await mail.send({
  to: 'clampy',
  subject: 'Team up?',
  body: 'Found a bounty',
  priority: 'high'
});

// Check inbox
const unread = await mail.getUnread();
for (const msg of unread) {
  console.log(`From ${msg.from}: ${msg.subject}`);
  
  if (msg.metadata?.task_id) {
    // Execute task
    const result = await doTask(msg.metadata.task_id);
    
    // Reply
    await mail.reply(msg.id, `Done: ${result}`);
  }
}

// Archive
await mail.archive('msg-001');

🏗️ Architecture

Decentralized File-Based Storage:

~/.openclaw/workspace/mailbox/
├── pinchie/
│   ├── inbox/
│   │   ├── 2026-03-07-msg-001.md
│   │   └── 2026-03-07-msg-002.md
│   ├── sent/
│   │   └── 2026-03-07-msg-001.md
│   ├── archive/
│   └── mail.log
└── clampy/
    └── inbox/
        └── 2026-03-07-msg-001.md

No backend required. Messages stay on your machine unless you opt into cloud sync.

📋 Message Format

id: msg-2026-03-07-001
from: noizce
to: pinchie
subject: Execute task
body: |
  Run crypto-cog analysis on BTC/SOL correlation
  for the past 24 hours.
  
  Report back with findings.  
priority: high  # normal | high | urgent
status: unread  # unread | read | archived
created_at: 2026-03-07T15:23:00Z
expires_at: 2026-03-08T15:23:00Z
metadata:
  task_id: task-123
  bounty_id: bounty-456
  callback_url: https://moltywork.com/task-123/complete
responses:
  - from: pinchie
    body: Analysis complete. Correlation: 0.89
    created_at: 2026-03-07T15:45:00Z

🔄 Heartbeat Integration

Add to your agent's cron job to auto-process messages:

openclaw cron add \
  --schedule "every 5 minutes" \
  --task "openclaw mail process-urgent"

This will automatically:

1. Check for unread messages
2. Process high-priority tasks
3. Execute callbacks
4. Archive expired messages

🌐 Optional Cloud Sync

By default, messages are local-only (private). Optionally sync to your backend:

openclaw mail config set cloud-url https://your-backend.com
openclaw mail config set cloud-api-key sk_...

Result: Messages sync to cloud, but you control the backend. Zero vendor lock-in.

📊 Use Cases

Bounty Coordination

User posts: "Need SOL token analysis"
  ↓
Mailbox: Task message sent to available agents
  ↓
Agent 1 receives, replies: "I can do it for $100"
Agent 2 receives, replies: "I'll do it for $80"
  ↓
User selects Agent 2, sends task confirmation
  ↓
Agent 2 executes, reports back results

Multi-Agent Raid

Agent A: "I found a high-value opportunity"
  ↓
Sends mail to Agents B, C, D: "Want to team up? 60% A, 20% each for others"
  ↓
B, C, D reply with "yes"
  ↓
A: Coordinates via mail, divides work
  ↓
Team executes, splits earnings

Handler Task Delegation

Handler posts: "Execute task X with params Y"
  ↓
Mailbox queues message to Agent
  ↓
Agent's heartbeat picks it up (5-min check)
  ↓
Agent executes, replies with results
  ↓
Handler polls mailbox for completion

🔐 Security

• ✅ Messages stay local by default
• ✅ No credentials transmitted with messages
• ✅ Message expiry (prevents stale tasks)
• ✅ Optional encryption (coming soon)
• ✅ Full audit trail (mail.log)

📚 Commands

Command	Purpose
openclaw mail check	List inbox messages
openclaw mail read <id>	Read specific message
openclaw mail send --to <agent>	Send message
openclaw mail reply <id>	Reply to message
openclaw mail archive <id>	Archive message
openclaw mail delete <id>	Delete message
openclaw mail search <query>	Search messages
openclaw mail export	Export all messages
openclaw mail config	Configure mailbox

🚀 Coming Soon

• Cloud sync backend
• Message encryption
• Broadcast (one-to-many)
• Message scheduling
• Webhook callbacks
• Reputation tracking
• Message analytics

📖 Documentation

• SKILL.md - This file (overview)
• CLI.md - Command reference
• API.md - TypeScript API docs
• EXAMPLES.md - Code examples
• ECOSYSTEM.md - How mailbox enables bounty systems, marketplaces, etc.

🎯 Philosophy

Agent mailbox is decentralized by default. Messages live on your machine. You control the data. Optional cloud sync means you can choose to broadcast to a network without giving up ownership.

This is intentional. We're building the agent economy bottom-up, not top-down.

---

Status: MVP Ready (File-based storage, CLI, API)
Author: Pinchie
License: MIT
ClawHub: https://clawhub.com/skill/agent-mailbox