Organization-managed Outlook mailboxes

Approved 2026-09-10; implementation in progress, uncommitted and unverified. This is the approved contract, not a claim of working product behavior. See the implementation plan.

Decision and boundaries

An organization administrator connects multiple Microsoft accounts from an admin Mailboxes page without creating North users. Managed mailbox identity is distinct from a North login, personal Outlook connection, and organization ingestion connector.

This restores real delegated mailbox capability after the external-task cutover, not its dead scheduler grants or /delegation UI. No application-wide Exchange permissions, shared-mailbox auto-discovery, new North account, automatic ingestion, subscriptions or scheduler. Personal connection behavior remains the default.

Administration and authority

• Admins add accounts, inspect connection state, reconnect the same Microsoft identity, disconnect, and grant/revoke existing organization members' access. Multiple connected accounts coexist; connecting never provisions a member.
• Grants are read or read+send. Organization admins implicitly manage, read and send through every managed mailbox in their organization; nonadmins cannot manage and can use only assigned mailboxes. Read cannot send, create a send-capable draft, or send a newsletter.
• Validate current actor membership, admin authority where required, target membership and organization ownership server-side. Removal from the organization, grant revocation/downgrade and disconnect must deny subsequent affected operations; stale caches or refresh work cannot revive authority.
• Reconnect preserves the managed identity and grants only for that same Microsoft identity; reject a different account rather than replacing credentials. Disconnect invalidates credential use and pending connection work; it does not delete North users or their history.

Discovery and tool selection

Native list_delegated_mailboxes and MCP north__list_delegated_mailboxes list all organization-managed mailboxes for admins and only assigned ones for nonadmins. Return safe identity, connection state and effective permissions; never credentials or unrelated members' grant details.

Existing recent-mail, search, thread, attachment, send, draft and newsletter tools accept optional mailbox_id on native and MCP surfaces. Omission keeps personal behavior. An explicit selector resolves exactly one authorized managed mailbox in the current organization for the requested read/send operation; unknown, cross-organization, unassigned, revoked, disconnected or reauth-required selections fail closed. Never silently retry against personal credentials or another mailbox.

Message, thread and attachment identifiers are interpreted against the selected source. Attachment-to-own-Drive uses that mailbox for source authorization but the caller's own personal Drive credentials and North Drafts destination. Mailbox access grants no destination Drive access. Immediate-send behavior remains unchanged: no scheduler, confirmation gate or automatic uncertain-send retry is introduced.

Storage and credential service

Use separate managed identities, encrypted credentials and member grants, not personal connector rows or retired scheduler grants. Enforce RLS, organization foreign-key integrity and member checks; prevent cross-organization identity/grant references and duplicate active identities within an organization. Credential ciphertext is service-only: neither browser routes nor ordinary database roles may read it. Public metadata and discovery expose no token material.

Define schema/policies in packages/db/src/schema/managed_mailbox.ts, export via packages/db/src/schema/index.ts, generate migrations with bun db:generate, and provision least-privilege grants in packages/db/scripts/provision-roles.ts. No hand-written migration or live database operation belongs to this work.

OAuth and lifecycle safety

Reuse existing OAuth authorization, PKCE storage, token refresh and encrypted-envelope helpers. Use the same registered Outlook callback URL: dispatch only on verified signed purpose, never an untrusted query flag. Bind state to actor, organization, managed mailbox ID, credential generation and redirect URI; enforce nonce/PKCE consumption, expiry, current membership/admin authority and same-identity reconnect.

Revocation fences must span callback completion, token refresh and credential persistence: a disconnected or superseded generation cannot commit new tokens or restore a connection. Recheck relevant authority before executing an operation; a previously issued token is not durable permission. Already accepted provider sends cannot be recalled or described as revoked retroactively.

Observed contract seam, not completion evidence

The uncommitted packages/connectors-core/src/managed-mailbox.ts currently defines ManagedMailboxMetadata with mailboxId, organizationId, email, displayName, accountKey, status connected | disconnected | requires_reauth, effective canManage/canRead/canSend, and admin-only optional grants. Grant permission is read | read_send; service DTOs use camelCase mailboxId, while tools use mailbox_id.

That file defines ManagedMailboxTokenResponse as internal-only and signed purpose managed_outlook_mailbox. Its state schema includes returnTo: /connections/outlook, nonce, actor/org/mailbox IDs, generation and redirect URI. These observed DTOs guide integration; they do not prove routes, persistence, authorization or UI are implemented.

Existing user and manual acceptance

Keep the current North Tips & Tricks user, history, ownership and sharing unchanged; no automatic deletion, migration or identity merge. The admin first connects that same Microsoft account as managed, then Careers, for later user-manual acceptance. Both addresses are usable by the same North principal under managed authority, without a second North login. This sequence is not executed by this documentation task.

Provenance and release boundary

User-reported PR #415 includes prior cutover head 2a20299b11 with green Actions. That is historical evidence only; this capability remains uncommitted/unverified. Retain the existing lane-specific plan/dual-review waiver. The user explicitly authorized Devin/Fable workers, superseding the earlier Astra-only preference. Neither waiver nor approval authorizes merge, deployment or live verification.