> ## Documentation Index > Fetch the complete documentation index at: https://docs.truu.ai/llms.txt > Use this file to discover all available pages before exploring further. # Microsoft Outlook This guide walks you through connecting Microsoft Outlook (Exchange Online) to TruU TOTAL for persona generation and threat detection. *** ## Overview TOTAL collects email activity events from Microsoft Outlook via Microsoft Graph API change notifications (webhooks). Events are streamed in real time — when an email is sent, received, forwarded, or a mailbox rule is created, TOTAL receives the notification within seconds. We collect **metadata only** — email content (subject, body, attachments) is never accessed or stored. **Connector Type:** Streaming (Webhooks via Microsoft Graph Change Notifications) *** ## Prerequisites * **Microsoft Entra ID** (Azure AD) access with **Application Administrator** or **Global Administrator** role * **Exchange Online** enabled for your organization * **Microsoft 365 E3/E5** or equivalent license * Approximately **20 minutes** to complete setup *** ## Step 1: Register an Application in Entra ID 1. Sign in to the [Azure Portal](https://portal.azure.com) 2. Navigate to **Microsoft Entra ID** → **App registrations** 3. Click **New registration** 4. Enter: * **Name**: `TruU TOTAL - Outlook Integration` * **Supported account types**: *Accounts in this organizational directory only* * **Redirect URI**: Leave blank 5. Click **Register** 6. On the app's **Overview** page, copy: * **Application (client) ID** * **Directory (tenant) ID** 7. Paste the Client ID and Tenant ID into the TruU Portal *** ## Step 2: Create a Client Secret 1. In your App Registration, go to **Certificates & secrets** 2. Click **New client secret** 3. Enter: * **Description**: `TOTAL Outlook integration` * **Expires**: Choose your organization's preferred expiry 4. Click **Add** 5. Immediately copy the secret **Value** — it will only be shown once 6. Paste the Client Secret value into the TruU Portal *** ## Step 3: Grant API Permissions 1. In the App Registration, click **API permissions** 2. Click **Add a permission** → **Microsoft Graph** → **Application permissions** 3. Add the following permissions: * `Mail.Read` — Read mail metadata across all mailboxes * `MailboxSettings.Read` — Read mailbox settings and rules * `User.Read.All` — Read user profiles for identity resolution 4. Click **Add permissions** 5. Click **Grant admin consent for \[Your Organization]** 6. Click **Yes** to confirm > All permissions are **read-only**. TOTAL cannot send, modify, or delete emails, nor can it access email content. *** ## Step 4: Verify Connectivity Once credentials are entered in the TruU Portal: 1. Click **Test Connection** — TOTAL will validate the credentials and confirm Graph API access 2. TOTAL will automatically create webhook subscriptions for mail activity 3. Real-time event streaming will begin within minutes *** ## Security & Privacy ### What We Access * **Read-only access** to email activity metadata via Microsoft Graph webhooks * Email send/receive events (sender ID, recipient count, timestamp — **not subject or body**) * Email forwarding and delegation activity * Mailbox rule creation and modification * Folder operations (create, move, delete) ### What We Don't Have Access To * Email content (subject lines, body text) * Attachment contents * Contact lists or address books * Calendar data (separate connector) * User passwords *** ## Updating or Rotating Credentials ### Rotate Client Secret (Recommended: Before expiry) 1. In Azure Portal, go to **Entra ID** → **App registrations** → `TruU TOTAL - Outlook Integration` 2. Go to **Certificates & secrets** 3. Click **New client secret** (create the new one before deleting the old one) 4. Copy the new secret value and paste it in the TruU Portal 5. After TOTAL confirms the new secret is active, delete the old secret ### Revoke Access To immediately remove TOTAL's access: 1. **Option A** — Disable in the TruU Portal 2. **Option B** — Remove the App Registration's API permissions in Entra ID 3. **Option C** — Delete the App Registration entirely *** ## Rate Limiting & Scalability ### Microsoft Graph Rate Limits (Outlook) | Parameter | Limit | | ----------------------------- | ------------------------------------------ | | **Global Graph API limit** | 130,000 requests per 10 seconds per app | | **Mail-specific limit** | 10,000 requests per 10 minutes per mailbox | | **Subscription max lifetime** | \~3 days for mail resources (auto-renewed) | | **Throttle response** | HTTP 429 with `Retry-After` header | ### Ingestion Capacity Outlook uses a **streaming/webhook model** — Microsoft pushes change notifications to TOTAL in near real-time, so throughput is not constrained by polling rate limits. The per-mailbox limits (10K req/10 min) apply only to supplementary enrichment calls, not to webhook delivery itself. A large enterprise with 100K+ users typically generates 5M–20M mail events/day. Webhook delivery capacity is effectively unlimited. ### Event Freshness Microsoft delivers change notifications within seconds of the mail event. TOTAL acknowledges and processes them immediately. End-to-end latency from event occurrence to TOTAL processing is typically **under 10 seconds**. ### Resilience TOTAL acknowledges webhook notifications immediately and processes them in the background. If the webhook endpoint is temporarily unavailable, Microsoft retries delivery with exponential backoff for up to 4 hours. Subscriptions are auto-renewed before their \~3-day expiry. If a subscription lapses, TOTAL creates a new one and performs a catch-up delta query to fill any gap. For outages exceeding 4 hours, the same delta query mechanism ensures no events are permanently lost. ### Connector Design TOTAL's webhook endpoint acknowledges notifications immediately and processes them asynchronously. Events are batched and published in per-user order to preserve sequence integrity for persona building. The webhook service scales horizontally behind a load balancer. All subscription scopes and batching parameters are tunable from the TruU Portal. *** # Part 2: Event Types & Data Schema ## Signal Classification | Signal Class | TOTAL Category | | -------------- | --------------- | | Communications | Activity, Email | ## Event Types We Ingest TOTAL subscribes to the following Microsoft Graph change notification resources for Outlook. Every event is tied to a specific user's mailbox — the human identity who sent, received, or acted on the email. ### Mail Events | Graph Resource | Change Types | Description | TOTAL Classification | | ------------------------- | ------------------------- | ---------------------------------------- | -------------------- | | `/users/{id}/messages` | created | New email received or sent | Email | | `/users/{id}/messages` | updated | Email read, flagged, or moved | Email | | `/users/{id}/messages` | deleted | Email deleted | Email | | `/users/{id}/mailFolders` | created, updated, deleted | Mail folder created, renamed, or deleted | Email | ### Mailbox Rule Events | Graph Resource | Change Types | Description | TOTAL Classification | | -------------------------------------------- | ------------ | ---------------------- | -------------------- | | `/users/{id}/mailFolders/inbox/messageRules` | created | New inbox rule created | Email | | `/users/{id}/mailFolders/inbox/messageRules` | updated | Inbox rule modified | Email | | `/users/{id}/mailFolders/inbox/messageRules` | deleted | Inbox rule deleted | Email | ### Mail Activity Metadata Collected Per Event For each mail event, TOTAL captures the following metadata fields (content is never accessed): | Field | Description | Example | | -------------------- | -------------------------------------------- | ----------------------------- | | `sender` | Sender identity (hashed or resolved to TUID) | `user-aad-id-001` | | `recipientCount` | Number of recipients | `3` | | `toRecipientDomains` | Recipient domain(s) — internal vs. external | `["acme.com", "partner.com"]` | | `hasAttachments` | Whether the email has attachments | `true` | | `importance` | Email importance level | `high` | | `isRead` | Whether the email has been read | `false` | | `isDraft` | Whether the email is a draft | `false` | | `internetMessageId` | Unique message identifier | `` | | `conversationId` | Thread/conversation identifier | `conv-id-001` | | `createdDateTime` | Timestamp of the event | `2026-03-15T09:15:00Z` | | `flag` | Follow-up flag status | `flagged` | | `categories` | User-applied categories | `["Project Alpha"]` | *** ## Sample Source Event (Microsoft Graph Change Notification — New Email) ```json theme={null} { "value": [ { "subscriptionId": "d4e5f6a7-b8c9-0123-defg-456789012345", "changeType": "created", "clientState": "total-verification-token", "resource": "users('user-aad-id-001')/messages('msg-graph-id-001')", "resourceData": { "@odata.type": "#Microsoft.Graph.message", "@odata.id": "users('user-aad-id-001')/messages('msg-graph-id-001')", "id": "msg-graph-id-001", "createdDateTime": "2026-03-15T09:15:00.000Z", "receivedDateTime": "2026-03-15T09:15:02.000Z", "sentDateTime": "2026-03-15T09:14:58.000Z", "hasAttachments": true, "importance": "high", "isRead": false, "isDraft": false, "internetMessageId": "", "conversationId": "conv-id-001", "from": { "emailAddress": { "name": "External Partner", "address": "partner@external.com" } }, "toRecipients": [ { "emailAddress": { "name": "Jane Doe", "address": "jane.doe@acme.com" } } ], "ccRecipients": [ { "emailAddress": { "name": "John Smith", "address": "john.smith@acme.com" } } ], "flag": { "flagStatus": "notFlagged" }, "categories": [] }, "tenantId": "tenant-id-001" } ] } ``` ## TOTAL Normalized Event ```json theme={null} { "event_id": "d4e5f6a7-b8c9-0123-defg-456789012345", "event_type": "EMAIL", "source": "OUTLOOK", "signal_type": "COMMUNICATIONS", "domain_id": "customer-domain-001", "tuid": "tuid-jane-doe-001", "timestamp": "2026-03-15T09:15:02.000Z", "payload": { "event_id": "msg-graph-id-001", "user": "jane.doe@acme.com", "action": "email_received", "from_domain": "external.com", "is_external_sender": true, "recipient_count": 2, "to_domains": ["acme.com"], "cc_domains": ["acme.com"], "has_attachments": true, "importance": "high", "is_read": false, "conversation_id": "conv-id-001" }, "raw_metadata": { "platform_event_id": "msg-graph-id-001", "change_type": "created", "from_address": "partner@external.com", "from_name": "External Partner", "to_count": 1, "cc_count": 1, "to_domains": ["acme.com"], "cc_domains": ["acme.com"], "from_domain": "external.com", "is_external": true, "has_attachments": true, "importance": "high", "is_read": false, "is_draft": false, "internet_message_id": "", "conversation_id": "conv-id-001", "flag_status": "notFlagged", "received_at": "2026-03-15T09:15:02.000Z", "sent_at": "2026-03-15T09:14:58.000Z", "created_at": "2026-03-15T09:15:00.000Z", "source_platform": "microsoft_outlook" }, "platform_event_id": "msg-graph-id-001", "platform_event_source": "MICROSOFT_GRAPH_OUTLOOK_API" } ``` *** ## How This Feeds TOTAL ### Persona Building Outlook events define a user's **email communication pattern** — who they correspond with, how frequently, at what times, and whether communication is internal or external. This builds a communication graph that anchors each persona's expected email behavior, including typical correspondents, volume patterns, and working hours. ### Anomaly Detection TOTAL's behavioral engine uses Outlook events to detect: * **Mailbox rule manipulation** — creation of forwarding rules that silently redirect email to external addresses (a hallmark of business email compromise) * **Exfiltration indicators** — sudden spikes in emails with attachments to external domains, or bulk email activity outside normal patterns * **Communication graph anomalies** — correspondence with unusual external domains or contacts not in the user's baseline * **Account compromise signals** — email activity from a mailbox during hours inconsistent with the user's established pattern * **Insider threat precursors** — gradual shifts in external communication patterns that precede data exfiltration ### Breach Lifecycle Coverage Outlook events provide primary coverage across **Intent Exposed** and **Scope / Lateral Movement** stages. Email is often the primary vector for both initial compromise (phishing) and data exfiltration, making it a critical signal for detecting threats at multiple points in the breach lifecycle.