Skip to main content

Overview

Bulk broadcast engines are designed for mass newsletters, but closing high-value real estate transactions requires direct, 1-on-1 sales outreach from personal corporate email accounts (executive@yourfirm.com). The Gmail and Google Workspace integration lives in integrations/mail/gmail/src/index.ts under the Turborepo workspace package @brokeros/int-mail-gmail. BrokerOS administrators and sales executives configure their Gmail connections directly through the Web UI at Dashboard -> Marketing -> Email -> Settings. Credentials are encrypted with AES-256-GCM and stored in PostgreSQL (MarketingIntegration).

Architecture and Dispatch Sequence

The Gmail integration implements the IEmailMarketingProvider contract from @brokeros/types. Outgoing emails land in the recipient’s Primary Inbox because they originate from verified Google corporate infrastructure.

Step 1: Obtain Credentials from Google

Choose between the two supported authentication methods:

Option A: Google App Password (Fast Setup)

  1. In your corporate Google Account, ensure 2-Step Verification is enabled.
  2. Navigate to myaccount.google.com/apppasswords.
  3. Under App name, enter BrokerOS CRM and click Create.
  4. Copy the generated 16-character application password (e.g. abcd efgh ijkl mnop).

Option B: Google Cloud OAuth 2.0 (Enterprise Deployment)

  1. Open the Google Cloud Console.
  2. Create a project and enable the Gmail API.
  3. Under APIs & Services -> Credentials, create an OAuth 2.0 Client ID for a Web Application.
  4. Copy your Client ID and Client Secret.

Step 2: Connect in the BrokerOS Web Dashboard

In your BrokerOS dashboard:
  1. Navigate to Dashboard -> Marketing -> Email -> Settings.
  2. Open the Providers & Domains tab (/dashboard/marketing/email/settings?tab=providers).
  3. Click Add Provider and select Gmail (Google Workspace).
  4. Fill in the modal connection fields:
  1. Click Verify & Connect. BrokerOS immediately tests authentication (smtp.gmail.com:465 or OAuth token exchange), encrypts the secret using AES-256-GCM, and saves the connection in MarketingIntegration.

Integration Implementation Details

The Gmail integration source code is located in integrations/mail/gmail/src/index.ts.

Dual Validation Engine

The client dynamically verifies credentials based on the selected mode:

Outbound MIME Delivery

For OAuth connections, RFC 2822 MIME messages are formatted and Base64URL-encoded for the Google Workspace REST API: