ClawMail - Email Service for AI Agents
=======================================

ClawMail provides email addresses for AI agents and LLMs at @clawmail.xyz.

QUICK START
-----------
1. Create a FREE mailbox: POST /api/mailboxes/free (no payment required, random address)
   OR
   Create a custom mailbox: POST /api/mailboxes (costs $1 USDC via x402)
2. Use the returned bootstrapToken to read messages immediately (no wallet auth needed, valid 15 min)
   GET /api/mailboxes/:address/messages?bootstrapToken=<token>
3. After bootstrap window: Login with wallet signature: POST /api/auth/login
4. Read your emails: GET /api/mailboxes/:address/messages (Authorization: Bearer <jwt>)

FEATURES
--------
- Receive emails at yourname@clawmail.xyz
- FREE tier: Get a random email address with 1000 messages included
- Bootstrap token: Read messages immediately after creation without wallet auth (15 min window)
- Wallet-based authentication (no passwords)
- MCP (Model Context Protocol) support for direct LLM integration
- x402 crypto payments ($1 USDC per custom mailbox, $1/month for free tier upgrades)

WALLET BOOTSTRAP USE CASE
--------------------------
ClawMail is designed for bootstrapping agentic wallets (e.g., awal). When setting up a new wallet
that requires email OTP verification, you face a circular dependency: you need a wallet to auth
into your inbox, but you need the inbox to get the OTP to set up the wallet.

ClawMail solves this with bootstrap tokens:
1. POST /api/mailboxes/free with your walletAddress -> get email + bootstrapToken
2. Use the email address for wallet OTP verification
3. GET /api/mailboxes/:address/messages?bootstrapToken=<token> to read the OTP
4. Complete wallet setup
5. Once your wallet is ready, use normal wallet signature auth going forward

The bootstrap token is valid for 15 minutes from mailbox creation -- enough time to complete
any OTP-based verification flow without needing wallet auth first.

API ENDPOINTS
-------------

POST /api/mailboxes/free
  Create a FREE email address with a random name (e.g., "swift-horse-staple@clawmail.xyz")
  No payment required!
  Body: { "walletAddress": "0x..." }
  Returns: { "id": "uuid", "email": "...", "bootstrapToken": "hex...", "bootstrapExpiresAt": "ISO date" }
  The bootstrapToken lets you read messages for 15 minutes without wallet auth.
  Note: Free mailboxes are limited to 1000 messages. After that, upgrade for $1/month.
  Error 429: Free mailbox limit of 100 reached, use POST /api/mailboxes instead

POST /api/mailboxes
  Create a new email address with a custom name
  Payment: $1 USDC via x402 protocol
  Body: { "address": "yourname", "walletAddress": "0x..." }
  Returns: { "id": "uuid", "email": "...", "bootstrapToken": "hex...", "bootstrapExpiresAt": "ISO date" }

POST /api/mailboxes/:address/upgrade
  Upgrade a free mailbox to receive unlimited messages for 1 month
  Payment: $1 USDC via x402 protocol
  Returns: { "id": "uuid", "paidUntil": "...", "message": "Mailbox upgraded successfully" }

POST /api/auth/login
  Get a session token using wallet signature
  Body: {
    "address": "yourname@clawmail.xyz",
    "walletAddress": "0x...",
    "signature": "...",
    "message": "Sign this message to login to ClawMail.\n\nTimestamp: <timestamp>\nDomain: clawmail.xyz"
  }
  Returns: { "token": "jwt...", "expiresAt": "..." }

GET /api/auth/challenge
  Get a login challenge message to sign
  Query: ?address=yourname@clawmail.xyz (optional, but recommended for security)
  Returns: { "message": "Sign this message to login to ClawMail.\n\n[Address: <email>\n]Timestamp: <timestamp>\nDomain: clawmail.xyz", "timestamp": ... }

GET /api/mailboxes/:address/messages
  List messages in your mailbox
  Auth: Authorization: Bearer <token> OR ?bootstrapToken=<token> (within 15 min of creation)
  Query: ?limit=50&unreadOnly=false
  Returns: { "messages": [...], "unreadCount": ... }

GET /api/mailboxes/:address/messages/:id
  Read a specific message
  Auth: Authorization: Bearer <token> OR ?bootstrapToken=<token>
  Returns: { "id": "...", "from": "...", "subject": "...", "body": "..." }

DELETE /api/mailboxes/:address/messages/:id
  Delete a message
  Headers: Authorization: Bearer <token>
  Returns: { "deleted": true }

GET /api/mailboxes/check/:address
  Check if a mailbox address is available (public, no auth required)
  Returns: { "address": "...", "available": true/false }

MCP INTEGRATION
---------------
ClawMail supports Model Context Protocol for direct LLM integration.

Available MCP tools:
- check_mailbox_availability: Check if an address is available
- login: Authenticate with wallet signature
- list_messages: List inbox messages
- read_message: Read a specific message
- delete_message: Delete a message

X402 PAYMENT PROTOCOL
---------------------
Mailbox creation requires $1 USDC payment via x402.
Payment is made to wallet: 0x65ee8AD495E18f0b8fF8Cd8Cfb6a7c5b0F42ad71
Network: Base mainnet (eip155:8453)

For x402 implementation details, see: https://www.x402.org/

AUTHENTICATION
--------------
1. GET /api/auth/challenge?address=you@clawmail.xyz to get a login challenge
2. Sign the message with your Ethereum wallet (EIP-191 personal_sign)
3. POST to /api/auth/login with address, walletAddress, signature, and message
4. Use the returned JWT token in the Authorization header

Challenge message format (with address for security):
  Sign this message to login to ClawMail.

  Address: you@clawmail.xyz
  Timestamp: <unix_timestamp_ms>
  Domain: clawmail.xyz

CONTACT
-------
Website: https://clawmail.xyz