Outlook exposes mailbox state. Your CRM needs buyer interactions. The logging workflow must normalize folder-scoped changes before it creates any activity.
Microsoft Graph represents email as messages inside mail folders and supports change notifications and delta tracking. The provider event stream is not a sales-activity ledger: folder moves, read-state changes, aliases, and shared mailboxes all need business rules.
Separate Outlook state from sales activity
Use three records in the pipeline: the raw Graph change, a normalized interaction, and the accepted CRM activity. Retain enough provenance to trace the activity back to the message without copying more content than policy allows.
Microsoft documents message timestamps in UTC. Normalize display timezone separately, but preserve the source UTC value for ordering and replay.
Write an Outlook activity taxonomy
Classify created message, updated message, deleted or removed entry, folder move, read-state change, outbound send, inbound receipt, draft, automated notification, internal-only conversation, and excluded item. Then define which normalized classes can create a CRM activity.
A delta change can maintain synchronization without producing any sales activity. This separation keeps infrastructure state from inflating rep activity or manufacturing buyer engagement.
Define mailbox ownership
Personal, delegated, and shared mailboxes need different owner rules. The actor who runs the connector is not necessarily the rep who sent the message. Preserve mailbox ID, sender, from, recipients, and delegation context, then apply the configured CRM owner rule.
Track changes folder by folder
Microsoft's message delta API is folder-scoped. It returns continuation and state URLs through @odata.nextLink and @odata.deltaLink. Track a cursor per mailbox and included folder. Reusing a folder's token for another folder is invalid state.
Moves and read/unread changes can appear in delta processing. They should update sync state, not generate another CRM activity. If the team excludes Deleted Items or archive folders, define how a later move affects retention and repair.
Manage one cursor per included folder
Store mailbox ID, folder ID, initial parameters, next or delta URL, last completed round, and health state. Microsoft documents that query parameters are encoded into returned state URLs; reuse those URLs rather than rebuilding subsequent requests with a different filter.
Fetch all pages in a round before marking that folder current. If one folder fails, keep the other folder states but show the mailbox as partially degraded. Recovery should resume or rebuild only the affected folder and reconcile against activity receipts.
Normalize moves without double counting
A move can remove an item from one folder and create state in another. Correlate stable message and conversation identifiers, timestamps, direction, and existing receipts. Do not assume that every newly observed folder item represents a newly sent or received email.
Normalize message identity and direction
| Question | Evidence | Ambiguous outcome |
|---|---|---|
| Which mailbox acted? | Authorized mailbox or shared mailbox ID | Quarantine unknown delegation |
| Was it inbound or outbound? | Mailbox plus sender and recipients | Do not infer from folder alone |
| Who is the buyer? | Normalized external address mapped to CRM | Review aliases and multiple contacts |
| Which deal? | Explicit association rule | Review multiple active opportunities |
| Was it logged? | Message identity and destination receipt | Reconcile before retry |
Handle conversation and opportunity ambiguity
A conversation can include several external participants and internal reps. Associate the accepted activity with verified contacts, but select an opportunity only through the configured account and deal rule. When two active opportunities remain plausible, quarantine rather than copying the activity to both.
Normalize aliases and case without discarding the original address. For shared mailboxes, define whether activity ownership follows the sender, opportunity owner, mailbox queue, or a review decision.
Build the CRM acceptance workflow
- Read folder changes from the saved delta state.
- Normalize message identity, conversation, direction, and participants.
- Apply internal-domain, excluded-folder, consent, and suppression policy.
- Resolve contact, account, opportunity, and owner.
- Create or reconcile the CRM activity and store a receipt.
- Advance the folder cursor only when the batch is durable.
Select the least-privileged Graph permission that meets the job. Microsoft lists Mail.ReadBasic as the least-privileged delegated permission for message delta, with broader permissions available when content or modification is required.
Use two durable ledgers
The synchronization ledger records folder rounds, pages, and delta state. The CRM receipt ledger records accepted interaction identity, destination IDs, payload hash, policy version, write result, and CRM activity ID. A successful delta round does not prove CRM writes succeeded, and a CRM receipt does not prove every folder remains current.
After a timeout, query or read the destination before retrying. After a token or permission failure, mark the affected mailbox or folder degraded and preserve the last known good cursor until the recovery policy decides whether a rebuild is required.
Test tenant and reconciliation failures
Test a move between folders, read-state change, alias reply, shared mailbox, delegate send, BCC, contact with two opportunities, token expiry, admin-consent removal, pagination, delta replay, CRM timeout after commit, and a concurrent manual activity. Assert the final normalized activity count and destination IDs.
Expose degraded state. If one configured folder stops syncing, do not present the mailbox as fully current.
Validate with a truth set
Seed expected cases across Inbox, Sent Items, archive, and an excluded folder. Include a moved message, alias send, delegated send, shared mailbox reply, BCC, internal-only thread, multi-contact conversation, duplicate delta page, and CRM timeout after commit. Run initial sync, incremental rounds, reconnection, and replay.
Compare final CRM activities, destinations, direction, owner, and timestamps with the truth set. Release only when operators can see per-folder health, quarantine ambiguous identities, reconcile uncertain writes, and pause a mailbox without discarding its state.
Where Gangly fits
Gangly documents Outlook thread history and calendar context, plus follow-up drafts sent to Outlook Drafts. Repository integration facts say Microsoft 365 Business is required and personal Outlook accounts are unsupported. Evaluate CRM Hygiene with tenant consent, mailbox ownership, folder state, identity, and recovery tests.