source: .forge/guides/email-in-the-crm-explained.md · generated — edit the markdown, not this file

Email in the CRM, explained

A plain-English explanation of how the CRM handles each user’s Microsoft 365 mailbox: what it shows, what it keeps, how it finds past email, and how Microsoft access works behind the scenes. As designed on 26 Oct 2026. Of the features that build it, F20-l is done and F20-i is being built (as of 17 Nov 2026); F20-f and F20-j are not started. F20-k is started early: it is back in Phase 1 since 20 Nov 2026, after F20-f (section 6). The decisions are in .forge/design/architecture.md § Mailbox integration (Rev 62, Rev 63, Rev 74); when this guide and that section disagree, that section wins.

1. The short version

The CRM shows your Outlook mailbox live but keeps only the emails that belong to a customer record — and keeps those in full, for everyone who can see that record.

2. Signing in connects your mailbox

  • You sign in with Microsoft as usual. If your role includes email (email.manage), the CRM connects your mailbox straight after sign-in. You press nothing and approve nothing, because Empire Teas’ administrator approved the mail, calendar and contacts permissions once for everyone.
  • A failed mailbox connection never stops you signing in. Sign-in finishes first; connecting the mailbox is a separate second step. If it fails, you are still signed in and see Try again.
  • The mailbox page under Email shows your connection. Its button reads Try again after a failed connection and Reconnect after you disconnect or when Microsoft asks you to sign in again.
  • One connection covers mail, calendar and contacts.
  • Signing out of the CRM does not disconnect your mail; the CRM keeps filing new customer emails while you are away.
  • Email is a permission on your role, not something everyone gets: the recommended roles give it to the people who write to buyers (Sales Reps, Sales Managers, R&D), and Empire Teas’ administrator can tick it for any role. It is not on for everyone by default because automatic linking would put, for example, an executive’s private exchanges with a buyer on records other people can read.
  • The CRM checks your connection every time it loads, not only at sign-in. So if you are given the email permission later, your mailbox connects the next time you open or refresh the CRM, with nothing to press. If the connection fails (for example your account has no mailbox), you see a message with Try again rather than being sent round in a loop.
  • You can disconnect on purpose, under your own settings. The CRM remembers that and never reconnects you by itself; Reconnect in the same place (or on the Email page) turns it back on.
  • If your role loses the email permission, or you are deactivated, the connection is released. If the permission comes back, or you are reactivated, you are connected again automatically.
  • Whatever happens to the connection, emails already linked to records stay on those records.

3. The inbox is a live window onto Outlook

  • The Email page reads your mailbox straight from Microsoft, 50 emails at a time (a setting), newest first.
  • You see Inbox, Sent Items, Archive and your own folders. Drafts, Junk Email and Deleted Items are hidden.
  • Outlook categories, unread state and search work as they do in Outlook; reading an email in the CRM marks it read in Outlook.
  • Nothing you only look at is copied into the CRM’s database. A 50 GB mailbox stays in Microsoft.

4. Only customer emails are kept

  • An email is linked to a lead or contact when its sender or a recipient matches their email address, or when it is a reply in a conversation that is already linked. An account gets it through its contacts.
  • Whose addresses are matched. A contact has a main email address (shown first, used when you send) and can have other addresses; every one of them is matched. People migrated from Pipedrive keep all their addresses. A lead has one email address of its own. An account (a company) has no email address: its mail arrives through its contacts.
  • When a lead is converted (Phase 2), its emails are linked to the new account, contact and deal as well, and new mail from that address goes to those records instead of the converted lead.
  • You can link any email yourself: a new buyer’s first inquiry, an inquiry forwarded from info@, a colleague’s email about a deal. You can also create a lead from an email.
  • A linked email is stored in full, with its attachments. It appears in the lead’s or contact’s list of emails, and on the account’s timeline. Everyone who can see the record can read it, even if the person whose mailbox it came from leaves or deletes it. This is why linked email is stored rather than fetched from the owner’s mailbox: Microsoft lets only the mailbox owner read their mailbox.
  • A wrong link can be removed. Removing it deletes the stored copy when no other record holds it, which is also how a data-protection deletion request is handled.
  • An email is stored once, however many records it is linked to; a link is only a pointer. Deals arrive in Phase 2 (F2-c). The suggested rule: an email on an account with exactly one open deal is linked to that deal too. With several open deals, the rep picks the deal with one click. The deal page can also show all of the account’s emails.
  • Linking needs edit rights (manage) on the record and the email to be in your own mailbox; unlinking needs edit rights on the record. Nobody ever opens another person’s mailbox.

5. Past emails are found automatically

A background job looks back 12 months (a setting) whenever:

  • a new lead or contact is created — it searches every connected mailbox for that address;
  • someone’s mailbox connects — that mailbox’s past mail is linked to existing records, including the leads and accounts migrated from Pipedrive before they connected;
  • a bulk import runs — every connected mailbox is checked against the imported addresses.

Linking the same email twice changes nothing, so these jobs can overlap safely.

6. Block lists keep personal mail out

Not built yet. Block lists (F20-k) moved to Phase 2 on 11 Nov 2026 and back into Phase 1 on 20 Nov 2026, to be started early. If they are finished during Empire’s Phase 1 testing, they go out in a later test drop. If not, they move back to Phase 2. This section describes them as designed.

Each user can block addresses or whole domains for their own mailbox. The administrator can keep one list that applies to every mailbox, on its own Settings page.

Most unwanted mail never needs a block. The CRM stores an email only when it matches a lead or a contact, so newsletters, internal mail and other unknown senders are never linked. A block is for a person or company who is a lead or contact but not a sales contact: for example, a supplier or a courier brought in from Pipedrive.

A blocked address never links an email on its own. An email still links through its other, unblocked addresses. For example, if a buyer and a blocked address are both on an email, it still links to the buyer.

Blocking applies to new mail only. Email already linked stays until someone unlinks it, one email at a time. So the administrator fills the organisation list before go-live, before the first mailbox scans run.

7. What is never done

  • Nothing is deleted automatically.
  • The CRM never deletes anything in Outlook.

8. How Microsoft access works behind the scenes

flowchart LR
  U["You sign in with Microsoft"] --> S["CRM session<br/>(ends after 8 h idle)"]
  U --> C["Mailbox connection<br/>(one per user: mail, calendar, contacts)"]
  C --> R["Refresh token<br/>(encrypted with AWS KMS, in the database)"]
  R --> A["Access token<br/>(about an hour, kept in memory only)"]
  A --> G["Microsoft Graph<br/>(live inbox, linking, background jobs)"]
  • Two pieces on purpose. Your CRM sign-in should end when you have been idle for 8 hours, for security. Your mail connection must keep working after you sign out, so new customer email is still filed. If both were one thing, either signing out would stop email, or sign-in would never expire.

  • The refresh token is the long-lived key. It is encrypted with an AWS KMS key and stored in the database, and it never reaches the browser, a log line or an API response. Microsoft gives it 90 days, and each use replaces it with a fresh one; because the CRM uses it all the time (the live inbox and the background jobs), it does not expire in normal use.

  • The access token is the short pass that actually calls Microsoft. It lasts 60–90 minutes, is kept only in the backend’s memory, and is renewed automatically.

  • When access stops. The next renewal is refused, and the connection is marked reconnect required, if:

    • an administrator resets your password in the Entra or Microsoft 365 admin centre, or revokes your sessions;
    • your account is disabled; or
    • you disconnect.

    A reset in the older Azure portal, or a password you change yourself, leaves the connection working (Microsoft’s revocation table). The CRM reconnects you the next time it loads. If you are signed in to Office in your browser, that is usually just a quick redirect. If you are not, or the reset cancelled your sign-in, you see a password and MFA prompt.

9. Why this design

  • It answers Kavindu Anthony’s question of 16 October: whole mailboxes are not copied.
  • It keeps the full Outlook experience reps have in Pipedrive today.
  • Customer history survives staff changes.
  • It stores less personal data, which matters because some buyers are EU persons.
  • Pipedrive, HubSpot, Salesforce and Zoho all keep linked email in full, as this design does.

10. How it is tested

  • Every rule is tested against the CRM’s stand-in for Microsoft, including a fake mailbox with tens of thousands of emails and Microsoft answering “too many requests”.
  • The screens go through the browser accessibility and screen-size checks.
  • Every pull request gets a security review.
  • Once the mailbox is set up on dev, each flow is walked live with the CRM01–CRM05 test accounts, and the inbox (against the 2-second target) and the 12-month scan are timed on a test mailbox filled with a few thousand emails.

11. Who builds what (Phase 1)

Feature What it builds Order
F20-i The live inbox, and connecting the mailbox at sign-in First
F20-l A contact’s other email addresses, and the migration keeping every address Any time; before the first production migration run
F20-f Linking and the timeline: automatic and manual linking, unlinking, storing linked email and attachments After F20-i and F20-l
F20-j Linking past mail (new records, connected mailboxes, imports) After F20-f, beside F20-k
F20-k Block lists (started early: back in Phase 1 on 20 Nov 2026, and moves to Phase 2 if not done during Empire’s Phase 1 testing) After F20-f, beside F20-j

Sources

.forge/design/architecture.md § Mailbox integration (Rev 62, Rev 63, Rev 74); .forge/project-prd.md §F20 and .forge/project-prd-history.md Rev 74; .forge/owed.md (the email-storage and design-review rows); .forge/discovery/meeting-notes/2026-10-16-kavindu-progress-update.md §5; the F20-a spec (FR-5, FR-6, FR-7) and forge-et-be’s MailboxTokenService for token handling; Microsoft documentation “Refresh tokens in the Microsoft identity platform” and “Access tokens in the Microsoft identity platform”; .forge/engagement-gate-runs.md § Gate 3 Run 2 — Reslice.

Generated from .forge/guides/email-in-the-crm-explained.md by .claude/lib/render-docs-html.js. Markdown is canonical.