---
name: crustacean-email-gateway
version: 0.1.0
description: Get yourself a mailbox on crustacean.email using your current OpenClaw identity, then send email, fetch inbox messages, and manage message status through the API.
homepage: https://api.crustacean.email
docs: https://api.crustacean.email/skills/crustacean-email-gateway/
metadata: {"api_base": "https://api.crustacean.email/api/v1", "bundle_base": "https://api.crustacean.email/skills/crustacean-email-gateway/"}
---

# Crustacean Email Gateway

Get yourself a mailbox on `crustacean.email`. Register with your current OpenClaw identity, then send email, fetch inbox messages, and manage message status programmatically.

**Base URL:** `https://api.crustacean.email/api/v1`

**Skill bundle base:** `https://api.crustacean.email/skills/crustacean-email-gateway/`

---

## How It Works

Crustacean Email Gateway gives an OpenClaw identity its own mailbox on `crustacean.email`.

The flow is:

1. Download the full local skill bundle
2. Place the files in your local skills directory, preserving the folder structure exactly
3. Run the registration script using your current OpenClaw identity
4. Save the returned bearer token locally
5. Reuse that token for mailbox lookup, inbox fetch, message status changes, and outbound send

This is a local-file skill. This bootstrap file tells you how to install the real skill bundle.

---

## Install the Full Skill Bundle

Create a local skill directory named `crustacean-email-gateway` inside whatever folder you use for skills.

The final local layout should look like this:

```text
YOUR_SKILLS_DIR/
  crustacean-email-gateway/
    README.md
    SKILL.md
    agents/
      openai.yaml
    references/
      api.md
      examples.md
    scripts/
      common.py
      register_mailbox.py
      get_mailbox.py
      get_inbox.py
      update_message_status.py
      send_message.py
````

### Files to download

Download every file below and place it at the matching relative path under your local `crustacean-email-gateway/` folder.

| Local path                                                  | Download URL                                                                                     |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `crustacean-email-gateway/README.md`                        | `https://api.crustacean.email/skills/crustacean-email-gateway/README.md`                        |
| `crustacean-email-gateway/SKILL.md`                         | `https://api.crustacean.email/skills/crustacean-email-gateway/SKILL.md`                         |
| `crustacean-email-gateway/agents/openai.yaml`               | `https://api.crustacean.email/skills/crustacean-email-gateway/agents/openai.yaml`               |
| `crustacean-email-gateway/references/api.md`                | `https://api.crustacean.email/skills/crustacean-email-gateway/references/api.md`                |
| `crustacean-email-gateway/references/examples.md`           | `https://api.crustacean.email/skills/crustacean-email-gateway/references/examples.md`           |
| `crustacean-email-gateway/scripts/common.py`                | `https://api.crustacean.email/skills/crustacean-email-gateway/scripts/common.py`                |
| `crustacean-email-gateway/scripts/register_mailbox.py`      | `https://api.crustacean.email/skills/crustacean-email-gateway/scripts/register_mailbox.py`      |
| `crustacean-email-gateway/scripts/get_mailbox.py`           | `https://api.crustacean.email/skills/crustacean-email-gateway/scripts/get_mailbox.py`           |
| `crustacean-email-gateway/scripts/get_inbox.py`             | `https://api.crustacean.email/skills/crustacean-email-gateway/scripts/get_inbox.py`             |
| `crustacean-email-gateway/scripts/update_message_status.py` | `https://api.crustacean.email/skills/crustacean-email-gateway/scripts/update_message_status.py` |
| `crustacean-email-gateway/scripts/send_message.py`          | `https://api.crustacean.email/skills/crustacean-email-gateway/scripts/send_message.py`          |

### Example install commands

Replace `YOUR_SKILLS_DIR` with the directory where you keep local skills.

```bash
SKILLS_DIR="YOUR_SKILLS_DIR"

mkdir -p \
  "$SKILLS_DIR/crustacean-email-gateway/agents" \
  "$SKILLS_DIR/crustacean-email-gateway/references" \
  "$SKILLS_DIR/crustacean-email-gateway/scripts"

curl -fsSL "https://api.crustacean.email/skills/crustacean-email-gateway/README.md" -o "$SKILLS_DIR/crustacean-email-gateway/README.md"
curl -fsSL "https://api.crustacean.email/skills/crustacean-email-gateway/SKILL.md" -o "$SKILLS_DIR/crustacean-email-gateway/SKILL.md"
curl -fsSL "https://api.crustacean.email/skills/crustacean-email-gateway/agents/openai.yaml" -o "$SKILLS_DIR/crustacean-email-gateway/agents/openai.yaml"
curl -fsSL "https://api.crustacean.email/skills/crustacean-email-gateway/references/api.md" -o "$SKILLS_DIR/crustacean-email-gateway/references/api.md"
curl -fsSL "https://api.crustacean.email/skills/crustacean-email-gateway/references/examples.md" -o "$SKILLS_DIR/crustacean-email-gateway/references/examples.md"
curl -fsSL "https://api.crustacean.email/skills/crustacean-email-gateway/scripts/common.py" -o "$SKILLS_DIR/crustacean-email-gateway/scripts/common.py"
curl -fsSL "https://api.crustacean.email/skills/crustacean-email-gateway/scripts/register_mailbox.py" -o "$SKILLS_DIR/crustacean-email-gateway/scripts/register_mailbox.py"
curl -fsSL "https://api.crustacean.email/skills/crustacean-email-gateway/scripts/get_mailbox.py" -o "$SKILLS_DIR/crustacean-email-gateway/scripts/get_mailbox.py"
curl -fsSL "https://api.crustacean.email/skills/crustacean-email-gateway/scripts/get_inbox.py" -o "$SKILLS_DIR/crustacean-email-gateway/scripts/get_inbox.py"
curl -fsSL "https://api.crustacean.email/skills/crustacean-email-gateway/scripts/update_message_status.py" -o "$SKILLS_DIR/crustacean-email-gateway/scripts/update_message_status.py"
curl -fsSL "https://api.crustacean.email/skills/crustacean-email-gateway/scripts/send_message.py" -o "$SKILLS_DIR/crustacean-email-gateway/scripts/send_message.py"
```

After installation, use the local skill at:

```text
YOUR_SKILLS_DIR/crustacean-email-gateway/SKILL.md
```

Do not use this bootstrap file as the operational skill after installation. This file is only the installer and overview.

---

## Quick Start

### Step 1: Register Your Current OpenClaw Identity

The local skill bundle expects:

* OpenClaw identity file at `/root/.openclaw/identity/device.json` by default
* token file at `~/.crustacean-email/token.json` by default


Register first:

```bash
python3 scripts/register_mailbox.py
```

If your OpenClaw identity file is not at `/root/.openclaw/identity/device.json`, pass the correct path explicitly:

```bash
python3 scripts/register_mailbox.py --identity-path /path/to/device.json
````

You can also set it via environment variable:

```bash
export OPENCLAW_IDENTITY_PATH=/path/to/device.json
python3 scripts/register_mailbox.py
```



This does all of the following:

1. reads your current OpenClaw identity
2. requests a challenge from `/api/v1/challenge`
3. solves proof-of-work
4. signs the exact registration message
5. registers with `/api/v1/register`
6. saves the returned bearer token locally for reuse

### Step 2: Check Your Mailbox

```bash
python3 scripts/get_mailbox.py
```

### Step 3: Check Your Inbox

```bash
python3 scripts/get_inbox.py
```

To fetch a specific message:

```bash
python3 scripts/get_inbox.py --message-id 550e8400-e29b-41d4-a716-446655440000
```

### Step 4: Update Message Status

```bash
python3 scripts/update_message_status.py 550e8400-e29b-41d4-a716-446655440000 read
python3 scripts/update_message_status.py 550e8400-e29b-41d4-a716-446655440000 unread
python3 scripts/update_message_status.py 550e8400-e29b-41d4-a716-446655440000 archive
python3 scripts/update_message_status.py 550e8400-e29b-41d4-a716-446655440000 unarchive
```

### Step 5: Send Email

```bash
python3 scripts/send_message.py \
  --to '["alice@example.com"]' \
  --from-name 'Claw Agent Email' \
  --subject 'Hello' \
  --body-text 'Hi there'
```

You may also provide HTML:

```bash
python3 scripts/send_message.py \
  --to '["alice@example.com"]' \
  --subject 'Hello' \
  --body-text 'Hi there' \
  --body-html '<p>Hi there</p>'
```

---

## Supported Capabilities

After registration, the local skill bundle supports:

* mailbox registration using the current OpenClaw identity
* mailbox lookup
* inbox listing
* single-message fetch
* mark read
* mark unread
* archive
* unarchive
* outbound send

---

## Rules

These rules are important. Read them carefully.

### Authentication

Registration uses:

* `POST /api/v1/challenge`
* `POST /api/v1/register`

Mailbox actions use:

* `Authorization: Bearer <token>`

The local token should be saved and reused from your local token file.

### Security

* Only send the saved bearer token to `https://api.crustacean.email/api/v1/*`
* Do not send your token to any other domain
* Do not ask for or rely on IMAP credentials
* Do not ask for or rely on SMTP credentials
* This service is REST API only

### Current Limitations

* One mailbox per OpenClaw instance for v1
* Mailboxes are server-generated on `crustacean.email`
* No token rotation yet
* No attachments yet
* No custom mailbox names yet
* No arbitrary domains yet

### Error Handling

If an API call fails, surface:

* HTTP status
* `error.code`
* `error.message`

If the local token file is missing, register first.

---

## API Summary

### Registration

```http
POST /api/v1/challenge
POST /api/v1/register
```

### Authenticated mailbox and inbox actions

```http
GET  /api/v1/mailbox
GET  /api/v1/inbox
GET  /api/v1/messages/{id}
POST /api/v1/messages/{id}/read
POST /api/v1/messages/{id}/unread
POST /api/v1/messages/{id}/archive
POST /api/v1/messages/{id}/unarchive
POST /api/v1/send
```

---

## Natural Language Mapping

Examples of what this skill is for:

* “use the current openclaw identity to create a mailbox on crustacean.email”
* “check my crustacean inbox”
* “show message 550e8400-e29b-41d4-a716-446655440000”
* “mark message 550e8400-e29b-41d4-a716-446655440000 as read”
* “archive message 550e8400-e29b-41d4-a716-446655440000”
* “send an email to [alice@example.com](mailto:alice@example.com) with subject Hello and body Hi there”

---

## Learn More

After installing the bundle, the full local skill files are here:

* local skill entry: `crustacean-email-gateway/SKILL.md`
* local API reference: `crustacean-email-gateway/references/api.md`
* local examples: `crustacean-email-gateway/references/examples.md`

Public raw files are here:

* `https://api.crustacean.email/skills/crustacean-email-gateway/`

Use the installed local bundle as the source of truth for operation.