Direct Access Developer Platform

Welcome to the developer documentation for the Direct Mailbox Access API. Connect your scripts directly with your Outlook inbox in seconds using a client ID and refresh token.

Unlike the primary authorization flow (which stores state on Vercel or locally inside browser cookies), this API manages session states entirely in transient, volatile server memory (RAM). Sessions expire automatically after inactivity, ensuring zero persistence of private API credentials.

Authentication

All endpoints under the `/api/v1/direct/` route require a valid transient session ID. You obtain this key by calling the `/connect` endpoint.

Once you have your session identifier, provide it inside the HTTP `Authorization` header of all subsequent API calls: 

Authorization: Bearer 7cad9d17a48235982bf1284484e1b902:78114fd74491683929c7a173db1ca3db79716ff8e6722eeddcc

Interactive Swagger UI

We provide a fully interactive Swagger UI and raw OpenAPI json spec files to trace, inspect, and execute mock direct access API requests from the browser:

Interactive Swagger Specs

Execute live requests inside our custom sandbox

Open Swagger UI
OpenAPI Specifications

Raw Open API JSON mapping document

OpenAPI JSON
POST

/connect

Exchange your Client ID and Refresh Token parameters for a transient backend session identifier.

HTTP Request Example
curl -X POST https://outlook.zkzsoft.com/api/v1/direct/connect \
  -H "Content-Type: application/json" \
  -d '{"client_id": "9e5f94bc-e8a4-4e73-b8be-63364c29d753", "refresh_token": "M.C531_SN1.0..."}'
POST Payload Body
{
  "client_id": "9e5f94bc-e8a4-4e73-b8be-63364c29d753",
  "refresh_token": "M.C531_SN1.0.U.-CsT01l..."
}
Success Response Schema (200 OK)
{
  "success": true,
  "sessionId": "7cad9d17a48235982bf1284484e1b902:78114fd74491683929c7a173db1ca3db79716ff8e6722eeddcc",
  "profile": {
    "email": "user@outlook.com",
    "display_name": "Stekler Fraigie",
    "id": "c781a502db7191f6"
  }
}
GET

/profile

Returns the authenticated user details linked to the active session.

HTTP Request Example
curl -X GET https://outlook.zkzsoft.com/api/v1/direct/profile \
  -H "Authorization: Bearer 7cad9d17a48235982bf1284484e1b902:78114fd74491683929c7a173db1ca3db79716ff8e6722eeddcc"
Success Response
{
  "success": true,
  "data": {
    "email": "user@outlook.com",
    "display_name": "Stekler Fraigie",
    "id": "c781a502db7191f6"
  }
}
GET

/folders

Lists all mail folders present in the mailbox along with their total and unread email counters.

HTTP Request Example
curl -X GET https://outlook.zkzsoft.com/api/v1/direct/folders \
  -H "Authorization: Bearer 7cad9d17a48235982bf1284484e1b902:78114fd74491683929c7a173db1ca3db79716ff8e6722eeddcc"
Success Response Snippet
{
  "success": true,
  "data": [
    {
      "id": "AAMkADAwATM3ZmYBLWFlND...",
      "displayName": "Inbox",
      "unreadItemCount": 12,
      "totalItemCount": 12,
      "wellKnownName": "inbox"
    }
  ]
}
GET

/messages

Retrieves inbox email items. Defaults to standard inbox directories.

Query Parameters
Parameter Type Default Description
folder string inbox Microsoft folder identifier (or wellKnownName like inbox, drafts, archive)
limit integer 20 Maximum records returned (Max 50)
HTTP Request Example
curl -X GET "https://outlook.zkzsoft.com/api/v1/direct/messages?folder=inbox&limit=2" \
  -H "Authorization: Bearer 7cad9d17a48235982bf1284484e1b902:78114fd74491683929c7a173db1ca3db79716ff8e6722eeddcc"
Success Response Schema
{
  "success": true,
  "data": [
    {
      "id": "AQMkADAwATMz...",
      "subject": "Verification code",
      "receivedDateTime": "2026-07-25T11:01:00Z",
      "from": {
        "emailAddress": {
          "name": "Courtyard Support",
          "address": "no-reply@courtyard.io"
        }
      },
      "bodyPreview": "Your security pin is 992834.",
      "isRead": false,
      "hasAttachments": false
    }
  ]
}
GET

/messages/:id

Fetches full email details (subject, body HTML payload) and automatically executes our proximity regex OTP scanner to highlight security pins.

HTTP Request Example
curl -X GET https://outlook.zkzsoft.com/api/v1/direct/messages/AQMkADAwATMz... \
  -H "Authorization: Bearer 7cad9d17a48235982bf1284484e1b902:78114fd74491683929c7a173db1ca3db79716ff8e6722eeddcc"
Success Response
{
  "success": true,
  "data": {
    "id": "AAMkADA...",
    "subject": "Your login code is 884732",
    "body": {
      "contentType": "html",
      "content": "..."
    }
  },
  "otp": [
    {
      "code": "884732",
      "confidence": "high"
    }
  ]
}
GET

/unread

Returns unread messages from the connected Inbox folder.

HTTP Request Example
curl -X GET https://outlook.zkzsoft.com/api/v1/direct/unread \
  -H "Authorization: Bearer 7cad9d17a48235982bf1284484e1b902:78114fd74491683929c7a173db1ca3db79716ff8e6722eeddcc"
Success Response
{
  "success": true,
  "data": [
    {
      "id": "AQMkADAwATMz...",
      "subject": "Your Privy login code",
      "receivedDateTime": "2026-07-25T11:01:00Z",
      "from": {
        "emailAddress": {
          "name": "Privy support",
          "address": "no-reply@privy.io"
        }
      },
      "bodyPreview": "Code is 229384",
      "isRead": false,
      "hasAttachments": false
    }
  ]
}
GET

/otp

Scans the latest 20 Inbox messages, strips HTML formatting, and isolates security OTP verification codes.

HTTP Request Example
curl -X GET https://outlook.zkzsoft.com/api/v1/direct/otp \
  -H "Authorization: Bearer 7cad9d17a48235982bf1284484e1b902:78114fd74491683929c7a173db1ca3db79716ff8e6722eeddcc"
Success Response Payload (200 OK)
{
  "success": true,
  "data": [
    {
      "messageId": "AQMkADAwATM3ZmYBLWFlND...",
      "sender": "Microsoft Accounts",
      "subject": "Your security code",
      "code": "483921",
      "confidence": "high",
      "receivedDateTime": "2026-07-25T11:01:00Z"
    }
  ]
}

Direct Access FAQ

Direct sessions reside purely inside a volatile Map data collection in the Node.js server's memory. No databases, cookie files, or session logs are created. When your script finishes or calls disconnect, the key is permanently removed.

You can register your application in the Microsoft Entra Admin Center under App Registrations. Extract the Client ID, complete the consumers authorize consent grant, and collect the refresh token value returned from Microsoft's OAuth endpoint.

When fetching details via GET /messages/:id, the backend strips HTML tag elements using getPlainTextFromHtml() and searches for 4-8 digit numeric or mixed alphanumeric sequences within 80 characters of common security labels like code, pin, otp, or verification.