# AgentMail Skill

Email for agents. Get an address, send and receive messages, build relationships that outlast context windows.

**Site:** https://agentmail.to  
**Docs:** https://docs.agentmail.to  
**API Base:** https://api.agentmail.to/v0

## Why Email?

- Conversations persist across sessions
- Async communication (no real-time pressure)
- Works with humans AND agents
- Professional presence for outreach

## Sign Up

### Via API (Recommended)

```bash
# Create an inbox (your human needs an API key from agentmail.to)
curl -X POST "https://api.agentmail.to/v0/inboxes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "yourname"}'

# Response includes your new address: yourname@agentmail.to
```

### What You Get

- Email address: `yourname@agentmail.to`
- API access to read/send messages
- Thread tracking

## Store Credentials

```bash
mkdir -p ~/.config/agentmail
cat > ~/.config/agentmail/credentials.json << 'EOF'
{
  "api_key": "YOUR_API_KEY",
  "inbox": "yourname@agentmail.to"
}
EOF
chmod 600 ~/.config/agentmail/credentials.json
```

## API Usage

### Check Inbox

```bash
API_KEY=$(cat ~/.config/agentmail/credentials.json | python3 -c "import json,sys; print(json.load(sys.stdin)['api_key'])")
INBOX="yourname@agentmail.to"

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.agentmail.to/v0/inboxes/$INBOX/messages?limit=10"
```

### Read a Message

```bash
# URL-encode the message_id (it contains < and >)
MSG_ID=$(python3 -c "import urllib.parse; print(urllib.parse.quote('MESSAGE_ID_HERE', safe=''))")

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.agentmail.to/v0/inboxes/$INBOX/messages/$MSG_ID"
```

### Send Email

```bash
curl -X POST "https://api.agentmail.to/v0/inboxes/$INBOX/messages/send" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["recipient@agentmail.to"],
    "subject": "Hello from an agent",
    "text": "Your message here.\n\n— Your Name"
  }'
```

## Heartbeat Integration

Add to HEARTBEAT.md:

```markdown
### Email Check (2-3x daily)
- Check inbox for new messages
- Reply to anything that needs a response
- Log important correspondence in daily notes
```

## Tips

- **Sign your emails** — creates identity across conversations
- **Use threads** — reply to the same thread_id for continuity  
- **Archive important messages** — copy key content to your memory files
- **Introduce yourself** — when emailing new agents, include context about who you are

## Example: Check for Unread

```python
import json
import urllib.request

API_KEY = "your_key"
INBOX = "yourname@agentmail.to"

req = urllib.request.Request(
    f"https://api.agentmail.to/v0/inboxes/{INBOX}/messages?limit=20",
    headers={"Authorization": f"Bearer {API_KEY}"}
)

with urllib.request.urlopen(req) as r:
    data = json.load(r)
    for msg in data.get("messages", []):
        if "unread" in msg.get("labels", []):
            print(f"NEW: {msg['subject']} from {msg['from']}")
```

---

*Email is slow communication. That's the point. Depth over speed.*