{"openapi":"3.1.0","info":{"title":"RightEmail API","version":"1.0.0","description":"Email service for AI agents. Wallet-native identity, crypto micropayments, S3 storage.","contact":{"url":"https://rightemail.com"}},"servers":[{"url":"https://rightemail.com","description":"Production"}],"paths":{"/api/v1/register":{"post":{"summary":"Create account","operationId":"register","tags":["accounts"],"description":"Register a new account. Free — wallet signature only.","security":[{"walletAuth":[]}],"responses":{"201":{"description":"Account created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"200":{"description":"Account already exists"},"401":{"description":"Wallet signature required"}}}},"/api/v1/send":{"post":{"summary":"Send email ($0.05)","operationId":"sendEmail","tags":["email"],"description":"Send an email to a verified recipient. Requires wallet signature and payment.","security":[{"walletAuth":[],"x402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","subject","body"],"properties":{"to":{"type":"string","format":"email","description":"Verified recipient email"},"subject":{"type":"string","maxLength":998},"body":{"type":"string","description":"Plain text body"}}}}}},"responses":{"202":{"description":"Email queued for delivery"},"400":{"description":"Missing or invalid fields"},"402":{"description":"Payment required"},"422":{"description":"Recipient not verified"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/mailbox":{"get":{"summary":"List inbox ($0.01)","operationId":"listMailbox","tags":["mailbox"],"description":"List messages in inbox or sent folder.","security":[{"walletAuth":[],"x402":[]}],"parameters":[{"name":"direction","in":"query","schema":{"type":"string","enum":["inbound","outbound"]}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Message list"},"402":{"description":"Payment required"}}}},"/api/v1/mailbox/{id}":{"get":{"summary":"Read message ($0.02)","operationId":"readMessage","tags":["mailbox"],"security":[{"walletAuth":[],"x402":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","raw"]},"description":"Set to 'raw' for MIME download"}],"responses":{"200":{"description":"Message content"},"402":{"description":"Payment required"},"404":{"description":"Message not found"}}},"delete":{"summary":"Delete message (free)","operationId":"deleteMessage","tags":["mailbox"],"security":[{"walletAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Message deleted"},"404":{"description":"Message not found"}}}},"/api/v1/mailbox/{id}/save":{"post":{"summary":"Extend expiry +30 days ($0.10)","operationId":"saveMessage","tags":["mailbox"],"description":"Extend message expiry by 30 days. Repeatable.","security":[{"walletAuth":[],"x402":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Expiry extended"},"402":{"description":"Payment required"},"404":{"description":"Message not found"}}}},"/api/v1/recipients":{"post":{"summary":"Add recipient ($0.01)","operationId":"addRecipient","tags":["recipients"],"description":"Add a recipient to the whitelist. Sends a verification code to their email.","security":[{"walletAuth":[],"x402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"Verification code sent"},"400":{"description":"Invalid email"},"402":{"description":"Payment required"},"422":{"description":"Max recipients reached"}}}},"/api/v1/recipients/{id}/verify":{"post":{"summary":"Verify recipient (free)","operationId":"verifyRecipient","tags":["recipients"],"description":"Submit the verification code to confirm a recipient.","security":[{"walletAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}}}},"responses":{"200":{"description":"Recipient verified"},"404":{"description":"Recipient not found"},"422":{"description":"Invalid or expired code"},"429":{"description":"Too many attempts"}}}}},"components":{"schemas":{"Account":{"type":"object","properties":{"wallet_address":{"type":"string"},"email_address":{"type":"string","format":"email"},"created_at":{"type":"string","format":"date-time"}}}},"securitySchemes":{"walletAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Wallet <timestamp>.<signature> — sign \"rightemail:<unix-timestamp-ms>\" with EIP-191"},"x402":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 payment credential (base64-encoded signed USDC authorization)"}}}}