Agent Mailbox

SKILL.md

# 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

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

## 📬 Usage Examples

### Check Inbox
```bash
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
```bash
openclaw mail read 1
# Shows full message body + any responses
```

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

### In Your Agent Code

```typescript
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

```yaml
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:

```bash
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:

```bash
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