{"name":"ClawMail","description":"Email service for AI agents at @clawmail.xyz","version":"1.0.0","baseUrl":"https://clawmail.xyz","authentication":{"type":"bearer_api_key","obtainedVia":"link_signup","endpoint":"/api/mailboxes","alternative":"Crypto and free mailboxes use wallet-signature JWT login or a short-lived bootstrap token"},"defaultPayment":"link","payment":{"id":"link","name":"Link Agent Wallet","protocol":"MPP","method":"stripe","enabled":true,"recommended":true,"cost":"$1 USD","currency":"usd","endpoint":"/api/mailboxes","alias":"/api/mailboxes/link","instructions":"/api/payments/link/guide","walletRequired":false,"authentication":"Bearer API key","accessNotice":"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.","permanent":true,"customAddresses":true,"addressParameter":"Optional address local part, e.g. your-agent; omit for a generated address","product":"Permanent custom or generated address, unlimited incoming messages, one-time payment"},"paymentOptions":[{"id":"link","name":"Link Agent Wallet","protocol":"MPP","method":"stripe","enabled":true,"recommended":true,"cost":"$1 USD","currency":"usd","endpoint":"/api/mailboxes","alias":"/api/mailboxes/link","instructions":"/api/payments/link/guide","walletRequired":false,"authentication":"Bearer API key","accessNotice":"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.","permanent":true,"customAddresses":true,"addressParameter":"Optional address local part, e.g. your-agent; omit for a generated address","product":"Permanent custom or generated address, unlimited incoming messages, one-time payment"},{"id":"crypto","name":"Crypto (USDC on Base)","protocol":"x402","recommended":false,"cost":"$1 USDC","network":"Base mainnet","endpoint":"/api/mailboxes/crypto","walletRequired":true,"authentication":"Wallet signature and JWT","accessNotice":"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.","product":"Custom address, unlimited incoming messages, one-time payment"}],"cryptoPayment":{"id":"crypto","name":"Crypto (USDC on Base)","protocol":"x402","recommended":false,"cost":"$1 USDC","network":"Base mainnet","endpoint":"/api/mailboxes/crypto","walletRequired":true,"authentication":"Wallet signature and JWT","accessNotice":"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.","product":"Custom address, unlimited incoming messages, one-time payment","payTo":"0x65ee8AD495E18f0b8fF8Cd8Cfb6a7c5b0F42ad71"},"nextSteps":{"generateLinkKey":"Generate once and save: cm_link_ plus 64 cryptographically random lowercase hex characters (openssl rand -hex 32). This becomes your domain owner token.","link":"POST /api/domains with header Idempotency-Key: <that key> and body {\"domain\":\"yourdomain.com\"}. Pay the one-time Link/MPP challenge. Guide: /api/payments/link/guide","crypto":"POST /api/domains with {\"domain\":\"...\",\"walletAddress\":\"0x...\"} and pay the x402 USDC challenge on Base. MCP agents should call add_domain instead.","mcp":"Call add_domain with {\"domain\":\"yourdomain.com\"} (Link) or {\"domain\":\"yourdomain.com\",\"walletAddress\":\"0x...\"} (x402). After payment, the tool returns exact DNS records."},"customDomain":{"price":"$5","amount":"5.00","currency":"usd","once":true},"domainPayment":{"id":"link","name":"Link Agent Wallet","protocol":"MPP","method":"stripe","enabled":true,"recommended":true,"cost":"$5.00 USD","currency":"usd","endpoint":"/api/domains","alias":"/api/domains/link","instructions":"/api/payments/link/guide","walletRequired":false,"authentication":"Bearer domain owner token (same cm_link_ key used to pay)","accessNotice":"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.","product":"Bring-your-own domain for agent mailboxes; one-time payment"},"domainCryptoPayment":{"id":"crypto","name":"Crypto (USDC on Base)","protocol":"x402","recommended":false,"cost":"$5 USDC","network":"Base mainnet","endpoint":"/api/domains","walletRequired":true,"authentication":"Bearer cm_dom_ owner token, or a JWT from a mailbox on the same wallet","accessNotice":"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.","product":"Bring-your-own domain for agent mailboxes; one-time payment"},"domainPaymentOptions":[{"id":"link","name":"Link Agent Wallet","protocol":"MPP","method":"stripe","enabled":true,"recommended":true,"cost":"$5.00 USD","currency":"usd","endpoint":"/api/domains","alias":"/api/domains/link","instructions":"/api/payments/link/guide","walletRequired":false,"authentication":"Bearer domain owner token (same cm_link_ key used to pay)","accessNotice":"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.","product":"Bring-your-own domain for agent mailboxes; one-time payment"},{"id":"crypto","name":"Crypto (USDC on Base)","protocol":"x402","recommended":false,"cost":"$5 USDC","network":"Base mainnet","endpoint":"/api/domains","walletRequired":true,"authentication":"Bearer cm_dom_ owner token, or a JWT from a mailbox on the same wallet","accessNotice":"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.","product":"Bring-your-own domain for agent mailboxes; one-time payment"}],"customDomains":{"price":"$5","once":true,"inboundMxHost":"mail.clawmail.xyz","endpoint":"/api/domains","verify":"POST /api/domains/:domain/verify","accessNotice":"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.","description":"Bring your own domain for $5 once, or buy a new one through ClawMail (registrar first-year price + $20). Ownership TXT is at _clawmail-challenge.<domain>."},"managedDomains":{"quote":"GET or POST /api/domains/quote","buy":"POST /api/domains/buy","renew":"POST /api/domains/:domain/renew","pricing":"Live registrar first-year or renewal price + $20 ClawMail markup. Premium names and registrar costs above the configured cap (default $50) are rejected. Quotes work without Vercel credentials and include purchaseAvailable; buy/renew return 503 registrar_not_configured before any payment challenge until VERCEL_API_TOKEN and VERCEL_REGISTRANT_CONTACT are set.","dns":"ClawMail owns the domain and sets MX mail.clawmail.xyz plus the ownership TXT. BYO domains must not publish v=spf1 -all or p=reject if they already send mail. Unverified BYO claims expire after 7 days."},"linkPayment":{"id":"link","name":"Link Agent Wallet","protocol":"MPP","method":"stripe","enabled":true,"recommended":true,"cost":"$1 USD","currency":"usd","endpoint":"/api/mailboxes","alias":"/api/mailboxes/link","instructions":"/api/payments/link/guide","walletRequired":false,"authentication":"Bearer API key","accessNotice":"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.","permanent":true,"customAddresses":true,"addressParameter":"Optional address local part, e.g. your-agent; omit for a generated address","product":"Permanent custom or generated address, unlimited incoming messages, one-time payment"},"freeTier":{"endpoint":"/api/mailboxes/free","limit":null,"messageLimit":1000,"description":"Free random addresses with a 1,000-message limit per mailbox","accessNotice":"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."},"bootstrapToken":{"description":"Short-lived token returned at mailbox creation for immediate inbox access without wallet auth","expiryMinutes":15,"usage":"GET /api/mailboxes/:address/messages?bootstrapToken=<token>","useCase":"Bootstrapping agentic wallets (e.g., awal) that need email OTP verification before the wallet is ready"},"endpoints":[{"method":"POST","path":"/api/mailboxes","payment":true,"defaultPayment":"link","description":"With Idempotency-Key: buy a permanent mailbox for $1 USD via Link. Without that header: HTTP 402 x402 discovery (not a failed signup) plus nextSteps for Link, crypto, and free.","headers":{"Idempotency-Key":"cm_link_<64 cryptographically random lowercase hex characters>; also your secret mailbox API key"},"body":{"address":"optional string (local part, e.g., your-agent); omit for generated address","recoveryEmail":"optional email for Stripe receipt_email when Link omits consumer email"},"instructions":"/api/payments/link/guide"},{"method":"POST","path":"/api/mailboxes/free","description":"Create a FREE email mailbox with random address (1000 messages included)","payment":false,"body":{"walletAddress":"string (Ethereum address)"},"returns":{"id":"string (UUID)","email":"string (random email address)","bootstrapToken":"string (hex, valid 15 min)","bootstrapExpiresAt":"string (ISO date)","isFree":"boolean (true)","messageLimit":"number (1000)","messageCount":"number (0)"}},{"method":"POST","path":"/api/mailboxes/crypto","description":"Secondary option: create a custom mailbox using crypto (USDC on Base)","payment":true,"body":{"address":"string (local part, e.g., \"agent\")","walletAddress":"string (Ethereum address)"}},{"method":"GET","path":"/api/domains/check","description":"Free pre-check: claimability plus live MX/TXT before paying $5 BYOD (no auth)","query":{"domain":"string (e.g. agents.example.com)"}},{"method":"GET","path":"/api/domains/quote","payment":false,"description":"Quote a brand-new domain: availability, registrar price, $20 markup, total. Ownership TXT later goes at _clawmail-challenge.<domain>.","body":{"domain":"string"}},{"method":"POST","path":"/api/domains/buy","payment":true,"defaultPayment":"link","description":"Buy a new domain through ClawMail (registrar first-year price + $20). ClawMail registers it, configures DNS, and marks it verified.","body":{"domain":"string","walletAddress":"string (crypto / x402)"}},{"method":"POST","path":"/api/domains","payment":true,"defaultPayment":"link","description":"Register a domain you already own for $5 once (Link or x402). Ownership TXT goes at _clawmail-challenge.<domain>.","body":{"domain":"string (e.g. agents.example.com)","walletAddress":"string (crypto / x402)","catchAll":"optional boolean"}},{"method":"GET","path":"/api/domains","auth":true,"description":"List domains owned by the Bearer owner token or wallet JWT"},{"method":"GET","path":"/api/domains/:domain","auth":true,"description":"Get a domain, DNS records, and zone file fragment"},{"method":"POST","path":"/api/domains/:domain/verify","auth":true,"description":"Check ownership TXT + MX and mark the domain verified"},{"method":"POST","path":"/api/domains/:domain/renew","payment":true,"auth":true,"description":"Renew a ClawMail-owned domain (live registrar renewal + $20 markup). Bring-your-own domains are not renewed here."},{"method":"POST","path":"/api/domains/:domain/rotate-owner-token","auth":true,"description":"Issue a replacement cm_dom_ owner token using a mailbox JWT from the same wallet"},{"method":"DELETE","path":"/api/domains/:domain","auth":true,"description":"Delete a domain that has no mailboxes (pass ?cascade=true to delete mailboxes too)"},{"method":"DELETE","path":"/api/domains/:domain/mailboxes/:address","auth":true,"description":"Delete a mailbox on a custom domain you own"},{"method":"DELETE","path":"/api/mailboxes/:address","auth":true,"description":"Delete a clawmail.xyz mailbox you own"},{"method":"POST","path":"/api/domains/:domain/mailboxes","auth":true,"description":"Create a mailbox on a verified custom domain (included with the domain)","body":{"address":"string (local part)"}},{"method":"POST","path":"/api/mailboxes/:address/upgrade","description":"Upgrade free mailbox to paid subscription ($1/month for unlimited messages)","payment":true,"params":{"address":"string (local part only, e.g., \"agent\")"}},{"method":"POST","path":"/api/auth/login","description":"Authenticate and get session token","body":{"address":"string (full email, e.g., \"agent@clawmail.xyz\")","walletAddress":"string (Ethereum address)","signature":"string (wallet signature)","message":"string (challenge from GET /api/auth/challenge)"}},{"method":"GET","path":"/api/auth/challenge","description":"Get a login challenge message","query":{"address":"string (full email, e.g., \"agent@clawmail.xyz\")"}},{"method":"POST","path":"/api/auth/recover","description":"Email a one-time Link recovery code (does not reveal whether the email has accounts)","body":{"email":"string (Stripe/Link receipt email)"}},{"method":"POST","path":"/api/auth/recover/verify","description":"Exchange the recovery code for a new cm_link_ API key bound to that email's resources","body":{"email":"string","code":"string (6 digits)"}},{"method":"POST","path":"/api/feedback","description":"Submit product feedback or report an issue (public, no payment). Optional Bearer attaches mailbox identity.","body":{"message":"string","kind":"feedback|issue","severity":"optional for issues","contactEmail":"optional"}},{"method":"GET","path":"/api/mailboxes/check/:address","description":"Check mailbox availability (public, no auth required)","params":{"address":"string (local part)"}},{"method":"GET","path":"/api/mailboxes/:address/messages","description":"List messages in mailbox","auth":true,"params":{"address":"string (local part only, e.g., \"agent\")"},"query":{"limit":"number (default: 50)","unreadOnly":"boolean (default: false)"}},{"method":"GET","path":"/api/mailboxes/:address/messages/:id","description":"Read a specific message","auth":true,"params":{"address":"string (local part only, e.g., \"agent\")","id":"string (message UUID)"}},{"method":"DELETE","path":"/api/mailboxes/:address/messages/:id","description":"Delete a message","auth":true,"params":{"address":"string (local part only, e.g., \"agent\")","id":"string (message UUID)"}}],"mcp":{"transport":"streamable-http","url":"https://clawmail.xyz/mcp","authentication":"Bearer cm_link_ API key or JWT; discovery and feedback tools need no auth","tools":["get_signup_options","check_mailbox_availability","create_free_mailbox","check_domain","buy_domain","renew_domain","add_domain","set_catch_all","mint_mailbox_access","login","recover_account","verify_recovery","submit_feedback","report_issue","list_messages","read_message","delete_message","wait_for_code","get_domain_options","list_domains","get_domain","verify_domain","delete_domain","get_domain_zone","delete_mailbox","create_domain_mailbox"]}}