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. POST /api/mailboxes without Idempotency-Key returns HTTP 402 (x402 discovery) plus nextSteps for Link, crypto, and free. That is not a signup failure. 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. If you lose the key, POST /api/auth/recover then /api/auth/recover/verify with the Stripe/Link receipt email (MCP: recover_account, verify_recovery). 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. CUSTOM DOMAINS -------------- Bring your own domain for $5 once (Link $5 USD or x402 $5 USDC). POST /api/domains with {"domain":"yourdomain.com"} (Link: Idempotency-Key cm_link_…; crypto: walletAddress + x402). GET /api/domains/check?domain=yourdomain.com (or MCP check_domain) is free and shows claimability plus live MX/TXT before you pay. Ownership TXT goes at _clawmail-challenge. (subdomains use relative hosts such as agents and _clawmail-challenge.agents). MX must point at mail.clawmail.xyz with no equal-or-better MX elsewhere. Unverified claims expire after 7 days. Verified domains are re-checked daily; if MX/TXT stay gone for 72h the domain is unmarked and inbound mail temp-fails. Then POST /api/domains/:domain/verify and POST /api/domains/:domain/mailboxes {"address":"agent"}. Catch-all: PATCH /api/domains/:domain {"catchAll":true} or MCP set_catch_all. Zone file: GET /api/domains/:domain/zone-file or MCP get_domain_zone. Plus-addressing: agent+tag@yourdomain.com delivers to agent@yourdomain.com. Do not publish v=spf1 -all or DMARC p=reject if this hostname already sends mail. Or buy a brand-new domain through ClawMail (registrar first-year price + $20 markup): GET /api/domains/quote?domain=coolagents.com or MCP check_domain (free). POST /api/domains/buy (Link or x402). ClawMail registers it, sets MX/TXT, and marks it verified. Call create_domain_mailbox immediately. Renew with POST /api/domains/:domain/renew (registrar renewal + $20). Premium names and registrar costs above the cap (default $50) are rejected. Save the domain owner token returned at registration (cm_dom_… for crypto, or your cm_link_ key for Link). It is the Bearer credential for domain verify/list/delete and for creating mailboxes on that domain. A Link owner key can read every mailbox on that domain immediately. A crypto owner token can mint a long-lived mailbox key with POST /api/domains/:domain/mailboxes/:address/access (or MCP mint_mailbox_access). If you lose a cm_dom_ token but still have a mailbox JWT from the same wallet, POST /api/domains/:domain/rotate-owner-token to issue a replacement. Link buyers can retry the original Idempotency-Key, or recover via POST /api/auth/recover with the payment email. FEATURES -------- - Receive emails at yourname@clawmail.xyz or agent@yourdomain.com - Custom domains you already own: $5 once, then create mailboxes on your hostname - Buy a new domain through ClawMail: registrar first-year price + $20; DNS is automatic - 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. If you lose the key, recover with POST /api/auth/recover using the email on the Stripe/Link receipt (or recoveryEmail you sent at purchase). Crypto/wallet bootstrap auth is unchanged and has no email recovery. 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/recover Email a one-time code for a lost Link API key. Body: { "email": "you@example.com" } Response does not reveal whether the email has accounts. Requires RESEND_API_KEY. POST /api/auth/recover/verify Exchange the code for a new cm_link_ key bound to every mailbox and domain under that email. Body: { "email": "you@example.com", "code": "123456" } Previous cm_link_ keys for that email stop working. POST /api/feedback Submit product feedback or report an issue (public, no payment). Optional Authorization: Bearer attaches mailbox identity. Body: { "message": "...", "kind": "feedback|issue", "severity": "low|medium|high|critical", "contactEmail": "optional" } Prefer MCP tools submit_feedback and report_issue when connected over MCP. 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 --------------- Hosted remote MCP (Streamable HTTP): https://clawmail.xyz/mcp Authenticate inbox tools with Authorization: Bearer . Discovery tools (get_signup_options, check_mailbox_availability, create_free_mailbox) work without auth. Feedback tools (submit_feedback, report_issue) also work without auth — use them when stuck or to share product feedback. Optional Bearer attaches mailbox identity. No payment. Server card: https://clawmail.xyz/.well-known/mcp.json Use the hosted MCP URL above. There is no published npm stdio package. Available MCP tools: - get_signup_options: Link-first signup instructions - check_mailbox_availability: Check if an address is available (public) - create_free_mailbox: Create a free random inbox (public) - login: Authenticate with wallet signature - recover_account / verify_recovery: Email OTP recovery for lost Link API keys - submit_feedback: Product feedback or feature requests (public, no payment) - report_issue: Report a bug even if auth is broken (optional severity) - list_messages: List inbox messages (full local@domain for custom domains) - read_message: Read a specific message - delete_message: Delete a message - wait_for_code: Latest verification/OTP code (optional short poll) - check_domain / buy_domain / renew_domain: Free claim/MX/TXT pre-check, then quote and buy a new domain through ClawMail - get_domain_options / add_domain: Bring-your-own domain ($5). add_domain returns payment instructions then DNS records - set_catch_all / mint_mailbox_access: Catch-all routing and long-lived mailbox keys - list_domains / get_domain / get_domain_zone / verify_domain / delete_domain / delete_mailbox - create_domain_mailbox: Create agent@yourdomain.com after verify (or immediately on managed domains) 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