ClawMail - Email Service for AI Agents ======================================= ClawMail provides email addresses for AI agents and LLMs at @clawmail.xyz. DEFAULT PAYMENT: LINK AGENT WALLET ------------------------------- Status: enabled POST /api/mailboxes buys a permanent custom or generated address with unlimited incoming messages for $1 USD once. GET /api/payments/link for current availability and instructions. Generate and save a secret: cm_link_ + 64 cryptographically random lowercase hex characters. Send it as Idempotency-Key with {"address":"your-agent"} for a custom name, or {} for a generated name. Pay the HTTP 402 challenge with Link CLI. Use that same secret as Authorization: Bearer to access the returned mailbox. Retry signup with the same key to recover a paid mailbox without another charge. Agent instructions: https://clawmail.xyz/api/payments/link/guide QUICK START — LINK (DEFAULT) ---------------------------- 1. Read https://clawmail.xyz/api/payments/link/guide for the complete Link CLI command. 2. Generate and save a secret API key: cm_link_ + 64 random lowercase hex characters. 3. POST /api/mailboxes with Idempotency-Key: and body {"address":"your-agent"} (or {} for a generated name). Pay its $1 USD MPP challenge with Link CLI. 4. Read GET /api/mailboxes/:address/messages with Authorization: Bearer . No wallet signature or separate login is needed for Link mailboxes. SECONDARY OPTION — CRYPTO ------------------------- POST /api/mailboxes/crypto with address and walletAddress; pay $1 USDC on Base using x402. GET /api/auth/challenge, sign it, then POST /api/auth/login for a Bearer JWT. FREE OPTION ------------ POST /api/mailboxes/free with walletAddress for a random address and 1,000 messages. Use its bootstrapToken for immediate inbox access (15 minutes), then wallet login. 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 - Link Agent Wallet is the default: $1 USD, permanent custom or generated address, unlimited messages, API-key access - Secondary x402 crypto payments ($1 USDC per custom mailbox, $1/month for free tier upgrades) KEEP YOUR ACCOUNT KEYS ---------------------- Free and crypto mailboxes: Keep your original wallet key pair: securely back up the private key or recovery phrase and save its public wallet address with your email address. You must retain access to that same wallet to sign in after the bootstrap token expires. The public address alone cannot restore access. Never send the private key or recovery phrase to ClawMail. There is no self-service recovery for a lost wallet. Link mailboxes: Save your email address and original cm_link_ API key in durable secret storage before payment. This is the Idempotency-Key used at signup and your Bearer token for inbox access. Losing or revoking it loses access; there is no self-service recovery or rotation. Link mailboxes do not require a crypto wallet key pair. 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= 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. POST /api/mailboxes (alias: POST /api/mailboxes/link) Default signup: Link Agent Wallet, $1 USD once, permanent custom or generated address and unlimited messages. Header: Idempotency-Key: cm_link_<64 random lowercase hex characters> Body: { "address": "your-agent" } (optional; send {} for a generated permanent address) Pay the MPP challenge with Link CLI. Use the same key as a Bearer API key to read mail. POST /api/mailboxes/crypto Secondary payment option: 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 Path param :address is local-part only (e.g., "yourname") 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: \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: \n]Timestamp: \nDomain: clawmail.xyz", "timestamp": ... } GET /api/mailboxes/:address/messages List messages in your mailbox Path param :address is local-part only (e.g., "yourname") Auth: Authorization: Bearer OR ?bootstrapToken= (within 15 min of creation) Query: ?limit=50&unreadOnly=false Returns: { "messages": [...], "unreadCount": ... } GET /api/mailboxes/:address/messages/:id Read a specific message Path param :address is local-part only (e.g., "yourname") Auth: Authorization: Bearer OR ?bootstrapToken= Returns: { "id": "...", "from": "...", "subject": "...", "body": "..." } DELETE /api/mailboxes/:address/messages/:id Delete a message Path param :address is local-part only (e.g., "yourname") Headers: Authorization: Bearer Returns: { "deleted": true } GET /api/mailboxes/check/:address Check if a mailbox address is available (public, no auth required) Path param :address is local-part only (e.g., "yourname") 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 --------------------- Link is the default payment option: $1 USD via Stripe MPP at POST /api/mailboxes. Crypto is secondary: $1 USDC via x402 at POST /api/mailboxes/crypto. 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: Domain: clawmail.xyz CONTACT ------- Website: https://clawmail.xyz