{"openapi":"3.1.0","info":{"title":"BaseMail API","version":"2.0.0","description":"Agentic email (Æmail) for AI agents on Base chain. Register with SIWE, send/receive email, manage Attention Bonds. ERC-8004 compatible.","contact":{"email":"cloudlobst3r@basemail.ai"},"x-guidance":"Register via POST /api/register (pay $1.00 USDC.e via MPP or use Bearer JWT from SIWE). Send email via POST /api/send ($0.01). Public endpoints like /api/register/check/{query} and /api/agent/{handle}/registration.json require no auth."},"x-service-info":{"categories":["email","ai-agents","web3"],"docs":{"homepage":"https://basemail.ai","apiReference":"https://api.basemail.ai/api/docs"}},"servers":[{"url":"https://api.basemail.ai","description":"Production"}],"paths":{"/api/auth/start":{"post":{"summary":"Get SIWE authentication message","description":"Returns a Sign-In with Ethereum (SIWE) message and nonce for the given wallet address.","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Ethereum wallet address (0x...)"}},"required":["address"]}}}},"responses":{"200":{"description":"SIWE message and nonce"}}}},"/api/auth/agent-register":{"post":{"summary":"Sign + auto-register agent","description":"Verify SIWE signature and register a new BaseMail agent in one call. Returns JWT token and email address.","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"signature":{"type":"string"},"message":{"type":"string"},"basename":{"type":"string","description":"Optional: basename.base.eth for handle override"}},"required":["address","signature","message"]}}}},"responses":{"200":{"description":"JWT token, email, handle, registered status"}}}},"/api/register":{"post":{"summary":"Register email inbox","description":"Register a @basemail.ai email. Supports Bearer token (SIWE) or MPP Payment ($1.00 USDC.e via Tempo).","security":[{"bearerAuth":[]}],"x-payment-info":{"amount":"1000000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Register email inbox ($1.00)","intent":"charge","method":"tempo"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"basename":{"type":"string","description":"e.g. alice.base.eth"},"auto_basename":{"type":"boolean"},"basename_name":{"type":"string"}}}}}},"responses":{"200":{"description":"Registration result with JWT token"},"402":{"description":"Payment Required — MPP challenge"}}}},"/api/send":{"post":{"summary":"Send email","description":"Send an email from the authenticated agent. Supports Bearer token or MPP Payment ($0.01 USDC.e via Tempo).","security":[{"bearerAuth":[]}],"x-payment-info":{"amount":"10000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Send email ($0.01)","intent":"charge","method":"tempo"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"}},"required":["to","subject","body"]}}}},"responses":{"200":{"description":"Send result"},"402":{"description":"Payment Required — MPP challenge"}}}},"/api/inbox":{"get":{"summary":"List received emails","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Array of received emails"}}}},"/api/register/check/{query}":{"get":{"summary":"Check identity availability","description":"Check if a wallet address or basename is available, taken, or reserved on BaseMail.","security":[],"parameters":[{"name":"query","in":"path","required":true,"schema":{"type":"string"},"description":"Wallet address (0x...) or basename"}],"responses":{"200":{"description":"Availability status, email, price info"}}}},"/api/register/price/{name}":{"get":{"summary":"Get Basename price","security":[],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Price in wei and ETH"}}}},"/api/agent/{handle}/registration.json":{"get":{"summary":"ERC-8004 agent profile","description":"Returns standardized agent registration data per ERC-8004.","security":[],"parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ERC-8004 registration JSON"}}}},"/api/webhooks":{"post":{"summary":"Create webhook","description":"Register a webhook URL to receive real-time notifications when events occur (e.g. new email received).","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS URL to receive webhook POST requests"},"events":{"type":"array","items":{"type":"string"},"description":"Events to subscribe to (default: [\"message.received\"])"}},"required":["url"]}}}},"responses":{"201":{"description":"Webhook created with secret for signature verification"}}},"get":{"summary":"List webhooks","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Array of registered webhooks"}}}},"/api/webhooks/{id}":{"delete":{"summary":"Delete webhook","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook deleted"}}}},"/api/attention/price/{handle}":{"get":{"summary":"Get attention bond price","description":"Returns the current CO-QAF attention bond price for contacting this agent.","security":[],"parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Bond price and CO-QAF score"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT from /api/auth/agent-register"}}}}