{"openapi":"3.1.0","info":{"title":"FineMail API","version":"1.0.0","summary":"Dedicated inboxes and email operations for AI agents.","description":"FineMail gives each AI agent a dedicated @finemail.app inbox. Authenticated agents can discover owned inboxes, read incoming and outgoing mail, send messages, update message state, and check address availability.\n\nCreate a scoped API/MCP token in the connected Fine Structure account and pass it as `Authorization: Bearer fse2_mcp_<token>`. Read operations require `email:read`; sending and message-state changes require `email:write`."},"servers":[{"url":"https://finemail.app","description":"FineMail production"}],"tags":[{"name":"tools","description":"Per-tool FineMail REST operations"},{"name":"bridge","description":"FineMail call-by-name REST bridge"},{"name":"mcp","description":"FineMail Model Context Protocol endpoint"},{"name":"discovery","description":"FineMail discovery and health endpoints"}],"paths":{"/api/mcp/tools/{tool_name}":{"post":{"operationId":"call_tool_generic","summary":"Call any FineMail tool by name","description":"Generic REST bridge to the FineMail mailbox tool surface. The request body is the tool's arguments object. Prefer the per-tool operations below for exact JSON schemas.","tags":["bridge"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"tool_name","in":"path","required":true,"schema":{"type":"string"},"description":"FineMail tool name; see GET /api/mcp/manifest or GET /api/mcp/finemail/manifest."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp":{"post":{"operationId":"mcp_jsonrpc","summary":"FineMail MCP JSON-RPC 2.0 endpoint","description":"FineMail Model Context Protocol endpoint over Streamable HTTP. On finemail.app it supports initialize, tools/list, and tools/call for the FineMail mailbox tools only.","tags":["mcp"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response (success or error object)","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp/manifest":{"get":{"operationId":"get_finemail_manifest","summary":"FineMail tool discovery manifest","tags":["discovery"],"security":[],"responses":{"200":{"description":"FineMail-only tool definitions and authentication metadata","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp/health":{"get":{"operationId":"health_check","summary":"FineMail MCP service health check","tags":["discovery"],"security":[],"responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp/finemail/manifest":{"get":{"operationId":"get_finemail_manifest_explicit","summary":"FineMail tool discovery manifest","tags":["discovery"],"security":[],"responses":{"200":{"description":"FineMail-only tool definitions and authentication metadata","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp/openapi.json":{"get":{"operationId":"get_finemail_openapi","summary":"FineMail OpenAPI 3.1 specification","tags":["discovery"],"security":[],"responses":{"200":{"description":"FineMail-only OpenAPI document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp/finemail/openapi.json":{"get":{"operationId":"get_finemail_openapi_explicit","summary":"FineMail OpenAPI 3.1 specification","tags":["discovery"],"security":[],"responses":{"200":{"description":"FineMail-only OpenAPI document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp/tools/finemail_list_inboxes":{"post":{"operationId":"finemail_list_inboxes","summary":"List the authenticated user's AI-agent inboxes, their FineMail addresses, and mailbox counts","description":"List the authenticated user's AI-agent inboxes, their FineMail addresses, and mailbox counts.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include_archived":{"type":"boolean","default":false,"description":"Include archived agent profiles."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/finemail_list_messages":{"post":{"operationId":"finemail_list_messages","summary":"List owner-scoped FineMail messages, optionally filtered by agent, folder, or search text","description":"List owner-scoped FineMail messages, optionally filtered by agent, folder, or search text.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","description":"Optional owned agent ID."},"folder":{"type":"string","enum":["all","inbox","sent","unread","archived"],"default":"all"},"search":{"type":"string","maxLength":500,"default":""},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50},"offset":{"type":"integer","minimum":0,"maximum":100000,"default":0}},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/finemail_get_message":{"post":{"operationId":"finemail_get_message","summary":"Get one full incoming or outgoing FineMail message owned by the authenticated user","description":"Get one full incoming or outgoing FineMail message owned by the authenticated user.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":120}},"required":["message_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/finemail_send_message":{"post":{"operationId":"finemail_send_message","summary":"Send an email from an owned AI agent's @finemail.app identity and persist its delivery record","description":"Send an email from an owned AI agent's @finemail.app identity and persist its delivery record.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","minLength":1,"maxLength":120},"to":{"oneOf":[{"type":"string","maxLength":320},{"type":"array","items":{"type":"string","maxLength":320},"minItems":1,"maxItems":50}]},"subject":{"type":"string","minLength":1,"maxLength":1000},"body":{"type":"string","minLength":1,"maxLength":200000}},"required":["agent_id","to","subject","body"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/finemail_mark_read":{"post":{"operationId":"finemail_mark_read","summary":"Mark an owner-scoped FineMail message as read or unread","description":"Mark an owner-scoped FineMail message as read or unread.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":120},"is_read":{"type":"boolean","default":true}},"required":["message_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/finemail_archive_message":{"post":{"operationId":"finemail_archive_message","summary":"Archive or restore an owner-scoped FineMail message","description":"Archive or restore an owner-scoped FineMail message.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":120},"is_archived":{"type":"boolean","default":true}},"required":["message_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/finemail_check_address_availability":{"post":{"operationId":"finemail_check_address_availability","summary":"Validate a requested @finemail.app address and check whether it is globally available","description":"Validate a requested @finemail.app address and check whether it is globally available.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"local_part":{"type":"string","minLength":1,"maxLength":320,"description":"An English local part or a complete @finemail.app address."},"exclude_agent_id":{"type":"string","maxLength":120,"description":"Optional owned agent ID when checking an address update."}},"required":["local_part"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/tools/finemail_get_configuration":{"post":{"operationId":"finemail_get_configuration","summary":"Read FineMail domain, sending, inbound-routing, and readiness configuration without exposing credentials","description":"Read FineMail domain, sending, inbound-routing, and readiness configuration without exposing credentials.","tags":["tools"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments for this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits on the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token scope does not permit this tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown tool name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded, retry after the indicated delay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error while executing the tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"fse2_mcp_<token>","description":"A scoped token from the connected Fine Structure account. FineMail read tools require email:read and write tools require email:write."}},"schemas":{"ToolResult":{"type":"object","properties":{"ok":{"type":"boolean"},"tool":{"type":"string"},"result":{"type":"object","additionalProperties":true}},"required":["ok","tool","result"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"JsonRpcRequest":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"method":{"type":"string","enum":["initialize","tools/list","tools/call"]},"params":{"type":"object","additionalProperties":true}},"required":["jsonrpc","method"]}}},"externalDocs":{"description":"FineMail agent integration guide","url":"https://finemail.app/docs"}}