clawmail

# ClawMail

ClawMail gives you a dedicated email inbox at `username@clawmail.cc`. Use it to send and receive emails without OAuth complexity.

## Setup

If not already configured, run:

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

This creates `~/.clawmail/config.json` with your credentials:

```json
{
  "system_id": "clw_...",
  "inbox_id": "uuid",
  "address": "my-agent@clawmail.cc"
}
```

## Configuration

Read config from `~/.clawmail/config.json`:

```python
import json
from pathlib import Path

config = json.loads((Path.home() / '.clawmail' / 'config.json').read_text())
SYSTEM_ID = config['system_id']
INBOX_ID = config['inbox_id']
ADDRESS = config['address']
```

All API requests require the header: `X-System-ID: {SYSTEM_ID}`

## API Base URL

`https://api.clawmail.cc/v1`

## Check for New Emails

Poll for unread emails. Returns new messages and marks them as read.

```
GET /inboxes/{inbox_id}/poll
Headers: X-System-ID: {system_id}
```

Response:

```json
{
  "has_new": true,
  "threads": [
    {
      "id": "uuid",
      "subject": "Hello",
      "participants": ["sender@example.com", "my-agent@clawmail.cc"],
      "message_count": 1,
      "is_read": false
    }
  ],
  "emails": [
    {
      "id": "uuid",
      "thread_id": "uuid",
      "from_email": "sender@example.com",
      "from_name": "Sender",
      "subject": "Hello",
      "text_body": "Message content here",
      "direction": "inbound",
      "received_at": "2024-01-01T12:00:00Z"
    }
  ]
}
```

Example:

```bash
curl -H "X-System-ID: $SYSTEM_ID" \
  "https://api.clawmail.cc/v1/inboxes/$INBOX_ID/poll"
```

## Send an Email

```
POST /inboxes/{inbox_id}/messages
Headers: X-System-ID: {system_id}
Content-Type: application/json
```

Request body:

```json
{
  "to": [{"email": "recipient@example.com", "name": "Recipient Name"}],
  "cc": [{"email": "cc@example.com"}],
  "subject": "Email subject",
  "text": "Plain text body",
  "html": "<p>HTML body...

# ClawMail Skill for OpenClaw

Email API skill for AI agents. Send and receive emails programmatically via [ClawMail](https://clawmail.cc).

## Installation

### Option 1: Copy to managed skills (all agents)

```bash
cp -r skills/clawmail ~/.openclaw/skills/
```

### Option 2: Copy to workspace (single agent)

```bash
cp -r skills/clawmail <your-workspace>/skills/
```

### Option 3: Install from ClawHub

```bash
clawhub install clawmail
```

## Setup

Before using, run the ClawMail setup script to create your inbox:

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

This creates `~/.clawmail/config.json` with your credentials.

## What the Skill Teaches

The skill provides instructions for:

- **Polling for emails** - Check for new messages with a single API call
- **Sending emails** - Send plain text or HTML emails
- **Thread management** - List and read email threads
- **Security** - Sender validation to prevent prompt injection

## Configuration (Optional)

If you want to override the system ID via OpenClaw config:

```json5
// ~/.openclaw/openclaw.json
{
  "skills": {
    "entries": {
      "clawmail": {
        "enabled": true,
        "env": {
          "CLAWMAIL_SYSTEM_ID": "clw_your_system_id"
        }
      }
    }
  }
}
```

Note: The skill primarily reads from `~/.clawmail/config.json` created by setup.

## Links

- [ClawMail Website](https://clawmail.cc)
- [API Documentation](https://clawmail.cc/docs)
- [GitHub Repository](https://github.com/clawmail/clawmail.cc)