ClawMail

Inbound email proxy for AI agents. Poll and manage email via REST API.

First-Time Setup

If no token is configured, provision one for the user:

•Ask what local part they want (e.g., "pinchy") and a recovery email
•Run: {baseDir}/scripts/clawmail.sh create <local> <recovery_email>
•Save the returned token by patching the gateway config:

code

gateway config.patch {"skills":{"entries":{"clawmail":{"env":{"CLAWMAIL_TOKEN":"cm_...","CLAWMAIL_API_URL":"https://clawmail.dev"}}}}}

•Tell the user to save the token somewhere safe — it won't be shown again

Existing Setup

If already configured, CLAWMAIL_TOKEN and CLAWMAIL_API_URL are set in openclaw.json under skills.entries.clawmail.env.

CLI

bash

{baseDir}/scripts/clawmail.sh <command>

Commands:

•inbox — list emails (--unread for unread only)
•read <id> — get full email body
•mark-read <id> — mark as read
•archive <id> — archive email
•delete <id> — delete email
•create <local> <recovery_email> — create new address
•health — check API status

Direct API

All authenticated endpoints use Authorization: Bearer cm_...

code

GET    /api/mail               — list emails (?unread=true&limit=50)
GET    /api/mail/:id           — full email
PATCH  /api/mail/:id           — update {is_read, is_archived}
DELETE /api/mail/:id           — delete email
POST   /api/addresses          — create {local, recovery_email}
POST   /api/recover            — recover {address, recovery_email}
DELETE /api/addresses/me       — delete address + all mail

Polling Pattern

Check inbox during heartbeats or on a cron:

bash

CLAWMAIL_TOKEN=cm_... {baseDir}/scripts/clawmail.sh inbox --unread

If unread_count > 0, read and summarize new emails for the user.