Create And Use New Agent Email Address

use this skill when you need to register an openclaw identity with crustacean email gateway, recover a lost bearer token for an already-registered instance,...

Security Scan

The skill's code, instructions, and resource use are consistent with its stated purpose (registering/recovering an OpenClaw identity and managing a mailbox via the Crustacean API); the main things to check are the local identity/private-key usage and the implicit dependency on the OpenSSL CLI.

Purpose & Capability

Name/description match the included scripts and API calls. All requested behavior (registration, recovery, mailbox/inbox/outbox/send, forwarding) is implemented and uses the Crustacean API; nothing in the repo asks for unrelated cloud credentials or unrelated system-level access.

Instruction Scope

Scripts read the local OpenClaw identity JSON (including the private key) and save a bearer token to a local path — this is required for signing registration/recovery and for persistence. This is expected for the stated purpose, but it means the skill will access a sensitive local private key file and write token files; review the identity path and token path before use.

Install Mechanism

There is no install spec (instruction-only), and all code is bundled with the skill. No remote downloads or installs are performed by the skill bundle itself.

Credentials

The skill does not request external API keys or unrelated env variables. It reads an OpenClaw identity file (private key) and optionally uses environment overrides for API base, identity path, and token path — these are proportional to registration/recovery. One mismatch: the scripts invoke the OpenSSL CLI but the skill metadata declares no required binaries.

Persistence & Privilege

The skill is not always-enabled and does not request elevated platform privileges. It persists a bearer token to a per-user token file (default ~/.crustacean-email/token.json), which is normal for this functionality.

Assessment

This bundle appears to do what it claims, but review and be aware of the following before installing: - The scripts read your OpenClaw identity JSON, including the private key, to sign registration/recovery requests; ensure you trust the skill and that the identity path (default /root/.openclaw/identity/device.json) is correct and intended to be used. - The code calls the OpenSSL CLI (openssl) to sign messages but the skill metadata does not declare openssl as a required binary — ensure openssl is available and from a trusted source on the system where the skill will run. If openssl is replaced by a malicious binary on your system, your private key could be exposed. - Tokens are saved to a local file (default ~/.crustacean-email/token.json). Confirm you are comfortable storing the mailbox bearer token there and that appropriate filesystem permissions protect it. - The scripts create a temporary file to hold the private key when signing; the file is removed after use but will exist briefly on disk. If your environment has strict requirements about ephemeral files, review this behavior. - If you want extra assurance, inspect the scripts yourself (they are bundled) and consider running them in a constrained environment or container the first time. Overall this skill is internally coherent for its stated purpose; the main concerns are the expected sensitive-file access and the implicit openssl dependency.

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 [e-mail]
   • Disable forwarding: python3 scripts/configure_forwarding.py --disable
10. Send:
    • python3 scripts/send_message.py --to '["[e-mail]"]' --subject 'Hello' --body-text 'Hi there'
    • HTML body example: python3 scripts/send_message.py --to '["[e-mail]"]' --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