source: .forge/discovery/research/m365-mailbox-integration.md · generated — edit the markdown, not this file

Microsoft 365 Mailbox Integration — How CRM Email Sync Works, and What We Need

Research note, 2026-08-18. Point-in-time — re-verify anything load-bearing at F20 spec time. Grounds: the F20/F21/F22 specs, the Microsoft 365 client asks in client/dependencies.md §1.2, and the mailbox model in design/architecture.md § Mailbox integration.

1. How CRM email integration works (the industry-standard model)

Every mainstream CRM (Pipedrive, HubSpot, Salesforce) uses the same shape:

  • Per-user mailbox connection. Each salesperson connects their own mailbox to the CRM via OAuth — a one-time “allow access” grant per person. The CRM holds a refresh token per user and syncs each connected mailbox separately. There is no single company-wide mailbox that everyone’s mail funnels through.
  • Auto-linking, not auto-sharing. Synced messages are matched to CRM records (contact, deal, lead, account) by participant email address plus threading heuristics. Linking determines where the email appears; separate visibility rules determine who can see it — a user’s inbox stays theirs, and typically only conversations linked to CRM records are visible to colleagues, subject to a private/shared setting.
  • Shared/team inboxes are a distinct connection type. A group address (info@, sales@) is connected as its own inbox owned by no individual, with an assignment rule for inbound items.
  • BCC drop-box as the fallback. For mail sent outside the CRM, a special BCC address files a copy against the matching records (Pipedrive calls this Smart BCC). Useful during migration/onboarding before everyone has connected.

2. What Empire’s reps are used to — Pipedrive specifics

  • One synced email account per user on the basic tiers (plan-tiered: Advanced 1 → Enterprise 5); a personal account is managed only by its user, while a team account connects a shared inbox that several users work.
  • Each user’s Pipedrive inbox is private and separate; default sharing is configurable — Private (conversations invisible to others) or Shared (record-linked conversations visible to colleagues on the same deal/contact).
  • Smart BCC exists on every plan as the non-synced fallback.
  • Rate ceiling ~40 mail actions/min/account (already carried in the PRD and the architecture’s per-mailbox token-bucket limiter).

Sources: Pipedrive Knowledge Base — Email sync, Email privacy and sharing, Smart BCC, Syncing multiple accounts.

Implication: our decided model (per-rep Graph connection + the shared info@ as an unowned first-class MailboxConnection, OQ-14) is a like-for-like replacement of what the team already knows — no behavioural retraining, minus Pipedrive’s plan-tier account limits.

3. Our model (decided — pointer, not a restatement)

design/architecture.md § Mailbox integration (separate from login OAuth) is authoritative: Microsoft Graph only (AD #16) behind the MailboxProvider seam; per-user connections with envelope-encrypted refresh tokens; the shared mailbox as its own connection + rate-limit bucket; push webhooks + periodic delta reconciliation; scheduled subscription renewal with a lapsed-subscription alarm (silent-failure mode) — the renewal interval derives from MailboxSubscriptions.MAXIMUM_EXPIRY, not from a figure restated here (this line said “every ~3 days” until 2026-09-23; the real ceiling is seven).

4. Microsoft Graph mechanics that shape the F20 build

  • Delegated permissions (each user consents in their own OAuth flow; the tenant admin pre-approves the set once): Mail.ReadWrite, Mail.Send, Calendars.ReadWrite, Contacts.ReadWrite, User.Read, offline_access; shared-mailbox access adds Mail.ReadWrite.Shared / Mail.Send.Shared.
  • Admin consent is a one-time tenant-level approval of that permission list against the app registration — after it, users self-connect with no IT involvement. This is the dependencies-doc §1.2 ask.
  • Change notifications (webhooks) require a publicly reachable HTTPS endpoint (dev environment URL or a tunnel during local work) and expire on the order of days for mail resources — hence the scheduled renewal job plus reconciliation poll rather than trusting push alone.
  • Throttling is per-app-per-mailbox; the token-bucket limiter in the worker absorbs it.

5. Dev/test tenancy — the 2026 reality

  • The Microsoft 365 Developer Program’s free sandbox is no longer generally available: eligibility now requires an active Visual Studio Professional/Enterprise standard subscription or qualifying Microsoft partner status (program FAQ, join via Visual Studio). Check whether Altrium holds either before assuming a free sandbox.
  • Practical alternatives: a paid test tenant (a few Microsoft 365 Business Basic seats, ~USD 6/user/mo — trivial against the build) or a 30-day trial tenant for spikes.
  • Day-to-day development therefore runs against an Altrium-held test tenant; Empire’s three test accounts (two reps + one manager + shared-mailbox access, dependencies §1.2) are for integration testing and UAT, where behaviour must match the real tenant’s sign-in policies, conditional access, and the actual shared mailbox. Keeping the two apart keeps client accounts out of the everyday build loop.

Superseded on both counts — F20-a spec decision D-3 (approved 2026-09-21). No separate Altrium M365 test tenant is held or planned: day-to-day development runs on the profile-scoped local/test stub (MailboxProvider seam), and a 30-day trial tenant covers any ad-hoc need with no lead time. The account count is also out of date — CRM01–05@empire.lk are provisioned in Empire’s own tenant; design/environments-and-identity.md §5 is the authoritative list. The paragraph above is kept as the dated June–July 2026 finding it was, not corrected in place, because rewriting research falsifies the record — but nothing should be inherited from it. This is the claim that reached client/dependencies.md §1.2 and had to be corrected there.

6. What we need from Empire Teas (pointer)

The dated, client-facing list is client/dependencies.md §1.2 (Rev 3): one-time administrator approval of the permission list, three licensed test accounts, and confirmation of which shared address(es) must appear in the CRM — all by Fri 18 Sep, ahead of the F20 build inside Phase 1.

Generated from .forge/discovery/research/m365-mailbox-integration.md by .claude/lib/render-docs-html.js. Markdown is canonical.