{"openapi":"3.1.0","info":{"title":"Outlook Personal Mailbox API","description":"A production-ready Developer REST API for managing Outlook, Hotmail, Live, and MSN personal mailboxes. The API validates credentials stateless on behalf of the user using Microsoft Graph API.","version":"1.0.0"},"servers":[{"url":"https://outlook.zkzsoft.com","description":"Production Server"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/me":{"get":{"summary":"Retrieve User Profile","description":"Retrieves the Microsoft profile details of the authenticated user.","responses":{"200":{"description":"Successfully retrieved profile details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileSuccessResponse"}}}},"401":{"description":"Unauthorized. Access token is expired, missing, or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"INVALID_TOKEN","message":"Access token expired."}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/mail/inbox":{"get":{"summary":"List Mailbox Messages","description":"Returns a paginated, filtered, and sorted list of mail messages from the specified folder.","parameters":[{"name":"folder","in":"query","description":"The target folder name (e.g. inbox, sent, drafts, deleted).","required":false,"schema":{"type":"string","default":"inbox"}},{"name":"top","in":"query","description":"The number of items to retrieve (pagination limit).","required":false,"schema":{"type":"integer","default":20}},{"name":"skip","in":"query","description":"The number of items to skip (pagination offset).","required":false,"schema":{"type":"integer","default":0}},{"name":"select","in":"query","description":"Comma-separated list of properties to include in the response (e.g. subject,sender).","required":false,"schema":{"type":"string"}},{"name":"orderBy","in":"query","description":"Sort order expression matching OData specs.","required":false,"schema":{"type":"string","default":"receivedDateTime desc"}},{"name":"filter","in":"query","description":"OData filter string to refine selection criteria.","required":false,"schema":{"type":"string"}},{"name":"unreadOnly","in":"query","description":"Flag to only fetch unread emails.","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Successfully retrieved message list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagesSuccessResponse"}}}},"400":{"description":"Bad Request. Invalid parameter value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/mail/search":{"get":{"summary":"Search Mailbox","description":"Performs keyword search queries across the user's mailbox context.","parameters":[{"name":"q","in":"query","description":"Search keyword query.","required":true,"schema":{"type":"string"}},{"name":"top","in":"query","description":"Pagination limit.","required":false,"schema":{"type":"integer","default":20}},{"name":"skip","in":"query","description":"Pagination offset.","required":false,"schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Successfully returned search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagesSuccessResponse"}}}},"400":{"description":"Bad Request. Missing 'q' query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/mail/otp":{"get":{"summary":"Scan Verification Codes (OTP)","description":"Scans subjects and body previews of the latest 20 inbox messages to extract OTP verification tokens.","responses":{"200":{"description":"Successfully returned OTP listings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpSuccessResponse"}}}}}}},"/api/v1/mail/{id}":{"get":{"summary":"Retrieve Message Details","description":"Fetches detailed contents of a specific email, including attachment info and HTML/text bodies.","parameters":[{"name":"id","in":"path","description":"The unique Microsoft Graph message ID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleMessageSuccessResponse"}}}},"404":{"description":"Message not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/mail/{id}/raw":{"get":{"summary":"Retrieve Raw Message JSON","description":"Returns the original, unfiltered Microsoft Graph API JSON response for a specific message.","parameters":[{"name":"id","in":"path","description":"The unique Microsoft Graph message ID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully returned raw message payload.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","description":"Original raw Microsoft Graph response payload."}}}}}}}}},"/api/v1/mail/send":{"post":{"summary":"Send Email Message","description":"Sends a new email message to a recipient.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmailRequest"}}}},"responses":{"201":{"description":"Email sent successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}}}},"400":{"description":"Bad Request. Invalid request payload parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/mail/reply":{"post":{"summary":"Reply to Email Message","description":"Replies to an existing message using a comment parameter.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyEmailRequest"}}}},"responses":{"201":{"description":"Reply sent successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}}}}}}},"/api/v1/auth/refresh":{"post":{"summary":"Refresh Access Token","description":"Exchanges a Microsoft Consumers OAuth refresh token for a new access token.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}}}},"responses":{"200":{"description":"Access token refreshed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenSuccessResponse"}}}},"400":{"description":"Bad Request. Microsoft returned invalid_grant or other errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"invalid_grant","message":"AADSTS7000012: The grant was obtained for a different tenant."}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter your Microsoft Graph OAuth Access Token. Obtain this token from the dashboard inspect window after completing the Microsoft OAuth sign-in flow."}},"schemas":{"ErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"SERVER_ERROR"},"message":{"type":"string","example":"Detailed description of the error."}}}}},"ProfileSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"email":{"type":"string","example":"john.doe@outlook.com"},"display_name":{"type":"string","example":"John Doe"},"id":{"type":"string","example":"a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6"},"userPrincipalName":{"type":"string","example":"john.doe@outlook.com"}}}}},"MessagesSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"AQMkADAwATMw..."},"subject":{"type":"string","example":"Your Verification Code: 483921"},"sender":{"type":"object","properties":{"emailAddress":{"type":"object","properties":{"name":{"type":"string","example":"Microsoft Accounts"},"address":{"type":"string","example":"account-security-noreply@accountprotection.microsoft.com"}}}}},"bodyPreview":{"type":"string","example":"Please enter the security verification code 483921 to access your account."},"receivedDateTime":{"type":"string","example":"2026-07-25T11:01:00Z"},"hasAttachments":{"type":"boolean","example":false},"isRead":{"type":"boolean","example":false}}}}}},"SingleMessageSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string","example":"AQMkADAwATMw..."},"subject":{"type":"string","example":"Verification Code"},"receivedDateTime":{"type":"string","example":"2026-07-25T11:01:00Z"},"sender":{"type":"object","properties":{"emailAddress":{"type":"object","properties":{"name":{"type":"string","example":"Microsoft"},"address":{"type":"string","example":"no-reply@microsoft.com"}}}}},"body":{"type":"object","properties":{"contentType":{"type":"string","example":"html"},"content":{"type":"string","example":"<html><body>Your security code is <b>483921</b>.</body></html>"}}},"hasAttachments":{"type":"boolean","example":false}}}}},"OtpSuccessResponse":{"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"}}}}}},"SendEmailRequest":{"type":"object","required":["to","subject","body"],"properties":{"to":{"type":"string","example":"recipient@example.com"},"subject":{"type":"string","example":"Developer API Integration"},"body":{"type":"string","example":"Hello from the Developer API client!"},"isHtml":{"type":"boolean","default":true,"example":true}}},"ReplyEmailRequest":{"type":"object","required":["messageId","comment"],"properties":{"messageId":{"type":"string","example":"AQMkADAwATMw..."},"comment":{"type":"string","example":"Thank you for the verification details. I will check the logs."}}},"RefreshTokenRequest":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string","example":"MC546_SN1.2.U.MsaArtifacts..."}}},"TokenSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"access_token":{"type":"string","example":"EwBIBM..."},"refresh_token":{"type":"string","example":"MC546_SN1..."},"expires_in":{"type":"integer","example":3600},"scope":{"type":"string","example":"offline_access email User.Read Mail.Read Mail.Send"},"token_type":{"type":"string","example":"Bearer"},"id_token":{"type":"string","example":"eyJhbGci..."}}}}}}}}