{"openapi":"3.1.0","info":{"title":"Direct Mailbox Access API","description":"REST API endpoints for direct mailbox integration using Client ID and Refresh Token credentials. Sessions are kept transiently in server memory.","version":"1.0.0"},"servers":[{"url":"https://outlook.zkzsoft.com","description":"Production Server"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/direct/connect":{"post":{"summary":"Establish Mailbox Connection","description":"Exchanges a Client ID and Refresh Token for an in-memory session. Returns a sessionId for subsequent authorizations.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string","description":"Azure application registration client identifier"},"refresh_token":{"type":"string","description":"OAuth 2.0 refresh token"}},"required":["client_id","refresh_token"]}}}},"responses":{"200":{"description":"Successfully established connection","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"sessionId":{"type":"string","example":"7cad9d17a48235982bf1284484e1b902:78114fd74491683929c7a173db1ca3db79716ff8e6722eeddcc"},"profile":{"type":"object","properties":{"email":{"type":"string","example":"user@outlook.com"},"display_name":{"type":"string","example":"Stekler Fraigie"},"id":{"type":"string","example":"c781a502db7191f6"}}}}}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Token exchange failed"}}}},"/api/v1/direct/profile":{"get":{"summary":"Retrieve User Profile","description":"Returns user profile details of the connected direct session.","responses":{"200":{"description":"Profile data retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"email":{"type":"string","example":"user@outlook.com"},"display_name":{"type":"string","example":"Stekler Fraigie"},"id":{"type":"string","example":"c781a502db7191f6"}}}}}}}}}}},"/api/v1/direct/folders":{"get":{"summary":"List Mail Folders","description":"Returns folder structure and unread counts for the connected account.","responses":{"200":{"description":"List of folders"}}}},"/api/v1/direct/messages":{"get":{"summary":"List Inbox Messages","description":"Retrieves list of inbox messages with unread and subject filters.","parameters":[{"name":"folder","in":"query","required":false,"schema":{"type":"string","default":"inbox"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"List of messages"}}}},"/api/v1/direct/messages/{id}":{"get":{"summary":"Get Message Details","description":"Fetches raw message details, parsed body content, and scanned security OTP verification codes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Detailed message payload with parsed OTP matches","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"},"otp":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"123456"},"confidence":{"type":"string","example":"high"}}}}}}}}}}}},"/api/v1/direct/search":{"get":{"summary":"Search Mailbox","description":"Queries the connected mailbox index using a search keyword.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Search matches list"}}}},"/api/v1/direct/unread":{"get":{"summary":"Retrieve Unread Inbox Messages","description":"Retrieves unread emails from the connected account's Inbox.","responses":{"200":{"description":"List of unread emails"}}}},"/api/v1/direct/otp":{"get":{"summary":"Scan Inbox for OTP Verification Codes","description":"Scans the latest 20 inbox messages to extract OTP verification codes.","responses":{"200":{"description":"List of detected verification codes","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"messageId":{"type":"string","example":"AQMkADAwATMw..."},"sender":{"type":"string","example":"Microsoft Accounts"},"subject":{"type":"string","example":"Your security code"},"code":{"type":"string","example":"483921"},"confidence":{"type":"string","example":"high"},"receivedDateTime":{"type":"string","example":"2026-07-25T11:01:00Z"}}}}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"UUID","description":"Format: Bearer <sessionId> (e.g. Bearer 7cad9d17a48235982bf1284484e1b902:78114fd74491683929c7a173db1ca3db79716ff8e6722eeddcc)"}}}}