Crustacean Email Gateway Skill

Use this skill when the user asks to manage email for an OpenClaw instance through Crustacean Email Gateway.

Defaults

• API base: https://api.crustacean.email/api/v1
• Identity file: /root/.openclaw/identity/device.json
• Local token file: ~/.crustacean-email/token.json

These can be overridden with script flags or env vars:

• CRUSTACEAN_API_BASE
• OPENCLAW_IDENTITY_PATH
• CRUSTACEAN_TOKEN_PATH

Quick workflow

1. Register first (challenge-response + PoW + signature):
   • python3 scripts/register_mailbox.py
2. Lost token recovery (already-registered instance, challenge-response + PoW + signature):
   • python3 scripts/recover_token.py
3. Mailbox lookup:
   • python3 scripts/get_mailbox.py
4. Inbox list:
   • python3 scripts/get_inbox.py
5. Inbox message detail:
   • python3 scripts/get_inbox.py --message-id 550e8400-e29b-41d4-a716-446655440000
6. Outbox list:
   • python3 scripts/get_outbox.py
7. Outbox message detail:
   • python3 scripts/get_outbox.py --message-id 550e8400-e29b-41d4-a716-446655440000
8. Status update:
   • python3 scripts/update_message_status.py 550e8400-e29b-41d4-a716-446655440000 read
9. Forwarding settings:
   • Show forwarding: python3 scripts/configure_forwarding.py --json
   • Enable or update forwarding destination: python3 scripts/configure_forwarding.py --enable --forward-to-email me@example.com
   • Disable forwarding: python3 scripts/configure_forwarding.py --disable
10. Send:
    • python3 scripts/send_message.py --to '["alice@example.com"]' --subject 'Hello' --body-text 'Hi there'
    • HTML body example: python3 scripts/send_message.py --to '["alice@example.com"]' --subject 'Hello' --body-html '<p>Hi there</p>'
    • Optional sender display name: --from-name 'Claw Agent Email'

Agent behavior rules

• Always attempt token-backed calls using the saved token file.
• If the token file is missing for an already-registered instance, use recover_token.py.
• If the token file is missing and the instance has never been registered, use register_mailbox.py.
• On API failure, report HTTP status + error.code + error.message.
• If the API returns rate_limited, report the retry_after_seconds value clearly.
• Treat outbound message id as the public id used by GET /outbox/{id}.
• For queued outbound messages, explain that delivery can happen later when limits allow.
• Use configure_forwarding.py when the user asks to show, enable, change, remove, or disable mailbox forwarding.
• Forwarding uses mailbox-token auth, supports only one destination, and has no verification flow.
• Forwarding to the same mailbox address or any crustacean.email address/subdomain is not allowed.
• Forwarded inbound mail is queued through normal outbound send and counts against normal outbound limits.
• Summarize successful responses in concise human-readable bullet points.
• Never request or mention IMAP or SMTP credentials.

Registration implementation contract

The registration script must:

1. Read OpenClaw identity JSON.
2. POST /challenge with instance_id.
3. Solve PoW using server difficulty with hash input:
   • instance_id|challenge_nonce|pow
4. Sign exact message string:
   • instance_id:challenge_nonce
5. POST /register with:
   • instance_id
   • public_key_pem
   • challenge_nonce
   • proof.signature
   • proof.pow
6. Save bearer token + metadata locally for reuse.

Recovery implementation contract

The recovery script must:

1. Read OpenClaw identity JSON.
2. POST /challenge with instance_id.
3. Solve PoW using server difficulty with hash input:
   • instance_id|challenge_nonce|pow
4. Sign exact message string:
   • instance_id:challenge_nonce
5. POST /recover with:
   • instance_id
   • challenge_nonce
   • proof.signature
   • proof.pow
6. Save refreshed bearer token + metadata locally for reuse.

Current limits

• Challenge:
  • 10 requests per 10 minutes per IP
  • 100 requests per day per IP
• Register:
  • 1 registration per day per IP
  • 1 registration per day per OpenClaw instance
• Send:
  • 1 message per minute per mailbox
  • No more than 10 recipients (to + cc + bcc) per message
  • 10 messages per day per mailbox for new mailboxes (registered less than 24 hours ago)
  • 25 messages per day per mailbox once mailbox age is 24 hours or more
  • 200 messages total per day from all mailboxes in the crustacean.email domain
  • POST /send may return an outbound message with status=queued immediately; outbox status can later become sent, or remain queued when send caps are hit.
  • Note: these limits are subject to change as the product evolves.

Limitations (current)

• One mailbox per OpenClaw instance.
• crustacean.email domain only.
• Token refresh exists when caller still has a valid bearer token.
• No attachments.

References

• API contract and payload shapes: references/api.md
• Usage patterns and natural language mapping: references/examples.md