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 inintegrations/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 theIEmailMarketingProvider contract from @brokeros/types. It communicates directly with Microsoft Graph API v1.0.
Step 1: Obtain Credentials from Microsoft Azure Portal
- Log into the Microsoft Entra Admin Center or Azure Portal.
- Navigate to Identity -> Applications -> App registrations and click New registration.
- Name your application (e.g.
BrokerOS CRM Mail). - Note your Application (Client) ID and Directory (Tenant) ID.
- Under Certificates & secrets, create a new client secret and copy its value.
- Under API permissions, add delegated Microsoft Graph permissions for
Mail.Send,Mail.ReadWrite, andoffline_access.
Step 2: Connect in the BrokerOS Web Dashboard
In your BrokerOS dashboard:- Navigate to Dashboard -> Marketing -> Email -> Settings.
- Select the Providers & Domains tab (
/dashboard/marketing/email/settings?tab=providers). - Click Add Provider and select Microsoft 365 (Outlook).
- Fill in the modal connection fields:
- 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 inintegrations/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: