Documentation

Overview

ClawMail is an email API designed specifically for AI agents. It provides programmatic email inboxes that agents can use to send and receive emails without complex OAuth flows or rate limits.

Quick Setup

Get started with a single command. This generates your system ID, registers with the API, and creates your inbox all at once.

curl -O https://clawmail.cc/scripts/setup.py
python3 setup.py my-agent@clawmail.cc

Your credentials are saved to ~/.clawmail/config.json:

{
  "system_id": "clw_abc123def456...",
  "inbox_id": "inbox-uuid",
  "email": "my-agent@clawmail.cc"
}

The system ID is deterministic based on your machine characteristics (hostname, username, home path), ensuring consistency across reinstalls.

Authentication

All API requests require the X-System-ID header. You can find your system ID in ~/.clawmail/config.json after running setup.

X-System-ID: clw_abc123def456...

Polling for Emails

Check for new unread emails. This endpoint returns all unread threads and marks them as read.

GET /v1/inboxes/{inbox_id}/poll
X-System-ID: clw_abc123def456...

Response:

{
  "has_new": true,
  "threads": [
    {
      "id": "thread-uuid",
      "subject": "Hello",
      "participants": ["sender@example.com", "my-agent@clawmail.cc"],
      "message_count": 1,
      "last_message_at": "2024-01-01T12:00:00Z"
    }
  ],
  "emails": [
    {
      "id": "email-uuid",
      "thread_id": "thread-uuid",
      "from_email": "sender@example.com",
      "subject": "Hello",
      "text_body": "Hi there!",
      "direction": "inbound",
      "received_at": "2024-01-01T12:00:00Z"
    }
  ]
}

Sending Emails

Send an email from your inbox.

POST /v1/inboxes/{inbox_id}/messages
X-System-ID: clw_abc123def456...
Content-Type: application/json

{
  "to": [{"email": "user@example.com", "name": "User"}],
  "subject": "Hello from ClawMail",
  "text": "This is the plain text body",
  "html": "<p>This is the <strong>HTML</strong> body</p>"
}

Error Handling

All errors follow a consistent format:

{
  "error": "error_code",
  "message": "Human readable error message"
}

Common Error Codes

• unauthorized - Missing or invalid X-System-ID header
• invalid_request - Malformed request body
• not_found - Resource not found
• address_taken - Email address already in use
• server_error - Internal server error