{
  "openapi": "3.0.3",
  "info": {
    "title": "Outlook Manager Public Mail API",
    "version": "3.3.2",
    "description": "Public mail read API. MUST use /api/v1/mail. MUST send X-API-Key. MUST encode + as %2B in path. List responses have no body fields—parse subject or call detail."
  },
  "servers": [{ "url": "https://weiruan.zmdsbk.com", "description": "Production" }],
  "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" },
      "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY" }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["detail", "code"],
        "properties": {
          "detail": { "type": "string" },
          "code": { "type": "string", "enum": ["unauthorized", "forbidden", "not_found", "bad_request", "unavailable", "error"] }
        }
      },
      "EmailItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Use this as message_id for detail" },
          "subject": { "type": "string" },
          "sender": { "type": "string" },
          "date": { "type": "string", "format": "date-time" },
          "folder": { "type": "string", "example": "INBOX" }
        }
      },
      "EmailList": {
        "type": "object",
        "required": ["email", "total", "emails"],
        "properties": {
          "email": { "type": "string" },
          "total": { "type": "integer" },
          "emails": { "type": "array", "items": { "$ref": "#/components/schemas/EmailItem" }, "description": "Never null; empty list is []" }
        }
      },
      "EmailDetail": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "subject": { "type": "string" },
          "sender": { "type": "string" },
          "recipient": { "type": "string" },
          "date": { "type": "string" },
          "content_text": { "type": "string", "nullable": true },
          "content_html": { "type": "string", "nullable": true }
        }
      }
    }
  },
  "paths": {
    "/api": {
      "get": {
        "summary": "Health / capability probe (no auth)",
        "security": [],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/v1/mail/{email}": {
      "get": {
        "summary": "List emails (no body content)",
        "parameters": [
          {
            "name": "email",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Root or plus-alias. Encode + as %2B. Example: user%2Btag@outlook.com"
          },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } },
          { "name": "folder", "in": "query", "schema": { "type": "string", "enum": ["all", "inbox", "junk"], "default": "all" } },
          { "name": "refresh", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "true to bypass cache when polling codes" }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailList" } } } },
          "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Blocked by global api_read_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Account not registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v1/mail/{email}/latest/{count}": {
      "get": {
        "summary": "Latest N emails",
        "parameters": [
          { "name": "email", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "count", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailList" } } } }
        }
      }
    },
    "/api/v1/mail/{email}/detail/{message_id}": {
      "get": {
        "summary": "Email detail with body",
        "parameters": [
          { "name": "email", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Value of emails[].id from list; URL-encode" }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDetail" } } } }
        }
      }
    },
    "/api/v1/mail/{email}/inbox": {
      "get": {
        "summary": "Inbox only",
        "parameters": [
          { "name": "email", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }
        ],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailList" } } } } }
      }
    },
    "/api/v1/mail/{email}/junk": {
      "get": {
        "summary": "Junk only",
        "parameters": [
          { "name": "email", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }
        ],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailList" } } } } }
      }
    }
  }
}