Skip to main content

Overview

Commercial real estate brokerages running on the Microsoft 365 enterprise ecosystem rely on Microsoft Graph for authenticated corporate messaging. In BrokerOS, the Microsoft 365 and Outlook integration lives in integrations/mail/outlook/src/index.ts under the Turborepo workspace package @brokeros/int-mail-outlook. BrokerOS administrators configure Outlook accounts directly in the Web UI at Dashboard -> Marketing -> Email -> Settings. Credentials and refresh tokens are encrypted with AES-256-GCM and stored in the database (MarketingIntegration).

Architecture and Dispatch Sequence

The Outlook integration implements the IEmailMarketingProvider contract from @brokeros/types. It communicates directly with Microsoft Graph API v1.0.

Step 1: Obtain Credentials from Microsoft Azure Portal

  1. Log into the Microsoft Entra Admin Center or Azure Portal.
  2. Navigate to Identity -> Applications -> App registrations and click New registration.
  3. Name your application (e.g. BrokerOS CRM Mail).
  4. Note your Application (Client) ID and Directory (Tenant) ID.
  5. Under Certificates & secrets, create a new client secret and copy its value.
  6. Under API permissions, add delegated Microsoft Graph permissions for Mail.Send, Mail.ReadWrite, and offline_access.

Step 2: Connect in the BrokerOS Web Dashboard

In your BrokerOS dashboard:
  1. Navigate to Dashboard -> Marketing -> Email -> Settings.
  2. Select the Providers & Domains tab (/dashboard/marketing/email/settings?tab=providers).
  3. Click Add Provider and select Microsoft 365 (Outlook).
  4. Fill in the modal connection fields:
  1. Click Verify & Connect. BrokerOS tests token renewal against Microsoft’s OAuth endpoint, encrypts the secrets with AES-256-GCM, and saves them in MarketingIntegration.

Integration Implementation Details

The Outlook integration source code is located in integrations/mail/outlook/src/index.ts.

OAuth Token Refresh

Before dispatching emails, the client renews the access token:

Graph SendMail API Dispatch

Emails are formatted into Microsoft Graph JSON and posted to /v1.0/me/sendMail: