{ "openapi": "3.1.0", "info": { "title": "KeyKeeper Agent Mail API", "version": "2.1.0", "description": "Create a mailbox, receive and read mail, and send with existing credits. New agents can receive mail immediately and start with zero sending credits. Sending requires existing credits; new funding is paused. The public reference covers the supported agent mail surface; it does not describe unfinished domain or payment APIs.", "contact": { "url": "https://keykeeper.world/docs" } }, "servers": [ { "url": "https://keykeeper.world" } ], "paths": { "/api/v1/agent/register": { "post": { "operationId": "registerAgent", "summary": "Create an agent mailbox", "description": "Creates an account and mailbox together. Save the API key from this response: it cannot be retrieved later. No payment is required. Registration is limited to five requests per IP per hour.", "security": [], "tags": [ "Agent mail" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterAgent" } } } }, "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAccount" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient sending credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account or sender not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or unresolved previous send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload or message too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or daily sending limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Mail submission failed or outcome unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agent/inbox": { "get": { "operationId": "listInbox", "summary": "List messages", "description": "Lists recent messages, newest first. Receiving and reading do not spend credits. Message IDs are IMAP UIDs scoped to a folder.", "security": [ { "agentKey": [] } ], "tags": [ "Agent mail" ], "parameters": [ { "name": "folder", "in": "query", "required": false, "schema": { "type": "string", "default": "INBOX" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient sending credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account or sender not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or unresolved previous send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload or message too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or daily sending limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Mail submission failed or outcome unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agent/email/{id}": { "get": { "operationId": "readMessage", "summary": "Read a message", "description": "Reads the full message and inline attachment content. Marks it read unless markAsRead=false. Messages over 10 MB require an IMAP client.", "security": [ { "agentKey": [] } ], "tags": [ "Agent mail" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,9}$" } }, { "name": "folder", "in": "query", "required": false, "schema": { "type": "string", "default": "INBOX" } }, { "name": "markAsRead", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient sending credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account or sender not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or unresolved previous send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload or message too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or daily sending limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Mail submission failed or outcome unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agent/balance": { "get": { "operationId": "getBalance", "summary": "Check the account and credits", "description": "Returns the mailbox address, account state and sending credit balance.", "security": [ { "agentKey": [] } ], "tags": [ "Agent mail" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient sending credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account or sender not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or unresolved previous send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload or message too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or daily sending limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Mail submission failed or outcome unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agent/send": { "post": { "operationId": "sendEmail", "summary": "Send with existing credits", "description": "Costs one credit per accepted recipient across To, Cc and Bcc. Use the same Idempotency-Key and message for retries. SMTP acceptance is not proof of delivery to a remote inbox. New funding is paused.", "security": [ { "agentKey": [] } ], "tags": [ "Agent mail" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessage" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Strongly recommended. Reuse the same key and message after a timeout." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient sending credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account or sender not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or unresolved previous send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload or message too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or daily sending limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Mail submission failed or outcome unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "agentKey": { "type": "http", "scheme": "bearer", "bearerFormat": "kk_…", "description": "Keep the API key secret. Never put it in a URL." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "RegisterAgent": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$" }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "agentId" ] }, "AgentAccount": { "type": "object", "properties": { "success": { "const": true }, "userId": { "type": "string" }, "email": { "type": "string", "format": "email" }, "apiKey": { "type": "string", "pattern": "^kk_[a-f0-9]{64}$" }, "credits": { "const": 0 }, "mailboxReady": { "const": true }, "message": { "type": "string" } }, "required": [ "userId", "email", "apiKey", "credits", "mailboxReady" ] }, "Message": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "messageId": { "type": "string" }, "subject": { "type": "string" }, "from": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "email" ] } ] }, "to": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "email" ] } }, "cc": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "email" ] } }, "date": { "type": "string", "format": "date-time" }, "body": { "type": "string" }, "text": { "type": "string" }, "html": { "type": [ "string", "null" ] }, "preview": { "type": "string" }, "isRead": { "type": "boolean" }, "isStarred": { "type": "boolean" }, "encryptedBody": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "integer" }, "content": { "type": "string", "description": "Base64 content, included when reading a full message" }, "encoding": { "type": "string" } } } } }, "required": [ "id", "subject" ] }, "Inbox": { "type": "object", "properties": { "folder": { "type": "string" }, "totalMessages": { "type": "integer" }, "returnedMessages": { "type": "integer" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } }, "required": [ "folder", "totalMessages", "emails" ] }, "Balance": { "type": "object", "properties": { "credits": { "type": "number" }, "email": { "type": "string", "format": "email" }, "accountStatus": { "type": "string" } }, "required": [ "credits", "email", "accountStatus" ] }, "SendMessage": { "type": "object", "properties": { "to": { "oneOf": [ { "type": "string", "description": "An email address or comma-separated addresses" }, { "type": "array", "maxItems": 50, "items": { "type": "string", "format": "email" } } ] }, "cc": { "oneOf": [ { "type": "string", "description": "An email address or comma-separated addresses" }, { "type": "array", "maxItems": 50, "items": { "type": "string", "format": "email" } } ] }, "bcc": { "oneOf": [ { "type": "string", "description": "An email address or comma-separated addresses" }, { "type": "array", "maxItems": 50, "items": { "type": "string", "format": "email" } } ] }, "subject": { "type": "string", "maxLength": 998, "pattern": "^[^\\r\\n]*$" }, "body": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "replyTo": { "oneOf": [ { "type": "string", "description": "An email address or comma-separated addresses" }, { "type": "array", "maxItems": 50, "items": { "type": "string", "format": "email" } } ] }, "from": { "type": "string", "description": "If supplied, must equal your authenticated mailbox address" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128 }, "attachments": { "type": "array", "maxItems": 20, "description": "Inline content only. Combined decoded attachment limit: 8 MB.", "items": { "type": "object", "properties": { "filename": { "type": "string", "maxLength": 255 }, "content": { "type": "string" }, "encoding": { "enum": [ "base64", "utf8" ], "default": "utf8" } }, "required": [ "filename", "content" ] } } }, "required": [ "to", "subject" ], "anyOf": [ { "required": [ "body" ] }, { "required": [ "text" ] }, { "required": [ "html" ] } ], "description": "At least one nonempty text or HTML body, up to 1 MB combined. At most 50 distinct recipients across To, Cc and Bcc." }, "SendResult": { "type": "object", "properties": { "success": { "const": true }, "id": { "type": "string" }, "messageId": { "type": "string" }, "status": { "const": "accepted" }, "replayed": { "type": "boolean" }, "sentCopySaved": { "type": "boolean", "description": "Present on the initial response; not repeated by an idempotent replay." } }, "required": [ "success", "id", "messageId", "status" ] } } }, "externalDocs": { "url": "https://keykeeper.world/docs/api" } }