Skip to content

feat: add multi-account Gmail and Outlook profiles - #7

Merged
404Dealer merged 3 commits into
masterfrom
feat/multi-email-profiles
Jul 11, 2026
Merged

404Dealer merged 3 commits into
masterfrom
feat/multi-email-profiles

Conversation

@404Dealer

@404Dealer 404Dealer commented Jul 11, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • add one-account-per-profile mailbox routing for multiple Gmail and Outlook/Microsoft 365 accounts through the existing single service, Unix socket, CLI, and Telegram bot
  • preserve the existing gmail-smtp compatibility mailbox whether exposed as implicit default or explicitly named, while rejecting legacy-reference replay against every other Gmail provider
  • add Microsoft Graph Inbox listing/read/verified mark-read, approval-gated move to Deleted Items, and authoritative-header unsubscribe support using immutable IDs
  • add named Gmail App Password and Outlook OAuth onboarding with atomic provider/profile persistence and conditional delegated Mail.ReadWrite
  • expose each mailbox profile's exact outbound provider key so Hermes can reply without reading private config or guessing conventions
  • update examples, operator documentation, wrappers, and the Hermes skill for multi-account workflows

Safety properties

  • references bind profile, backend, folder, and exact backend identity
  • Outlook message operations use folder-scoped Inbox endpoints, so stale references fail closed after a message leaves Inbox
  • Gmail legacy v1 references are accepted only by the unique gmail-smtp compatibility provider, regardless of its displayed profile name
  • mixed-profile and mixed-backend operations fail closed
  • Gmail Trash remains native IMAP MOVE with required MOVE/UIDPLUS and no delete/EXPUNGE fallback
  • Outlook Trash uses only Graph move to deleteditems; Graph DELETE is structurally rejected and move responses are bounded and identity-verified
  • Outlook unread listing scans a bounded newest-200 window and filters locally
  • Outlook refresh responses validate returned scopes when present, persist rotations before use, and are bounded to 64 KiB
  • unsubscribe still uses authoritative List-Unsubscribe headers only, with CR/LF-bearing Graph header values rejected
  • no credentials, tokens, private config, Telegram identifiers, or personalized unsubscribe endpoints are exposed to Hermes

Compatibility

  • no-profile Gmail onboarding still writes gmail-smtp
  • no-profile Outlook onboarding remains send-only
  • named Outlook mailbox onboarding requests and validates delegated Mail.ReadWrite
  • one service, one Telegram bot, one Unix socket, and one CLI remain the deployment model

Verification

  • npm test — 138/138 passed
  • npm run build
  • focused profile/Outlook/OAuth/SMTP/Trash/executor suites
  • built mailbox/OAuth/SMTP CLI help
  • production wrapper help and bash -n scripts/*.sh
  • npm pack --dry-run
  • example config profile resolution and skill frontmatter validation
  • git diff --check
  • cached added-line secret/danger scan (only deliberate fake-token and delete-rejection fixtures matched)

Not performed

  • no deployment or production restart
  • no live OAuth flow or Microsoft Graph mailbox call
  • no live mailbox mutation

Stacked on feat/approved-unsubscribe / PR #6.

Summary by CodeRabbit

  • New Features

    • Added bounded mailbox profiles for multiple Gmail and Outlook inboxes.
    • Added mailbox CLI support for listing profiles, selecting profiles, reading messages, marking messages read, and proposing trash or unsubscribe actions.
    • Added Outlook inbox access, including message reading, read-state updates, Deleted Items moves, and unsubscribe proposals.
    • Added profile-aware Gmail and Outlook OAuth onboarding with required access controls.
  • Documentation

    • Updated setup guides, configuration examples, security guidance, and feature descriptions for multi-mailbox workflows and approval requirements.

Copilot AI review requested due to automatic review settings July 11, 2026 00:15
@coderabbitai

coderabbitai Bot commented Jul 11, 2026 •

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@404Dealer, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 47 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ec606f7d-ff57-44e4-8244-05c8560cb1c8

📥 Commits

Reviewing files that changed from the base of the PR and between a7f6f55 and 5ca1fdf.

📒 Files selected for processing (6)
  • src/mailbox-broker/gmail-unsubscribe.ts
  • src/mailbox-broker/protocol.ts
  • src/mailbox-broker/server.ts
  • src/providers/email-outlook.ts
  • tests/mailbox-profiles.test.ts
  • tests/outlook-provider.test.ts
📝 Walkthrough

Walkthrough

The change adds named Gmail and Outlook mailbox profiles, profile-bound message references, Outlook Graph mailbox operations, profile-aware approval execution, and updated OAuth onboarding, configuration, documentation, and tests.

Changes

Multi-profile mailbox expansion

Layer / File(s) Summary
Profile configuration and onboarding
config.example.yaml, src/mailbox-broker/profiles.ts, src/oauth/*, src/smtp/*, tests/*
Adds named mailbox profile configuration, profile-aware Gmail and Outlook onboarding, delegated Outlook mailbox scopes, persisted profile bindings, and validation tests.
Profile-bound references and client protocol
src/mailbox-broker/adapter.ts, src/mailbox-broker/protocol.ts, src/mailbox-broker/reference.ts, src/mailbox-client.ts, src/schema.ts
Adds Gmail v2 and Outlook v2 references, profile selection, canonical identity validation, profile discovery, and longer reference limits.
Multi-backend broker operations
src/mailbox-broker/*, src/index.ts, tests/mailbox-profiles.test.ts, tests/outlook-mailbox.test.ts
Routes mailbox requests through Gmail or Outlook adapters and implements profile-aware listing, reading, marking read, trash, unsubscribe, and socket handling.
Outlook OAuth and Graph transport
src/oauth/outlook.ts, src/oauth-setup.ts, src/providers/email-outlook.ts, src/providers/outlook-token-client.ts, tests/outlook-provider.test.ts
Adds conditional mailbox scopes, shared token refresh handling, restricted Graph requests, and the updated Outlook send path.
Approval execution and mailbox presentation
src/executor.ts, src/bot.ts, src/mailbox-broker/*-proposal.ts, README.md, docs/*, skill/SKILL.md
Uses provider-keyed executors, validates approved snapshot identity, renders backend-specific previews, and documents bounded multi-account mailbox workflows.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Hermes
  participant MailboxClient
  participant MailboxBrokerServer
  participant GmailOrOutlookAdapter
  participant ApprovalStore
  Hermes->>MailboxClient: request profile-bound mailbox operation
  MailboxClient->>MailboxBrokerServer: send JSON request
  MailboxBrokerServer->>GmailOrOutlookAdapter: resolve profile and access mailbox
  GmailOrOutlookAdapter-->>MailboxBrokerServer: return messages or proposal snapshot
  MailboxBrokerServer->>ApprovalStore: store trash/unsubscribe proposal
  ApprovalStore-->>Hermes: return pending approval status
Loading
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main change: adding multi-account Gmail and Outlook profiles.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/multi-email-profiles

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@404Dealer
404Dealer changed the base branch from feat/approved-unsubscribe to master July 11, 2026 04:17

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mailbox-broker/gmail-unsubscribe.ts`:
- Around line 308-312: Update executeHttps to also validate snapshot.backend
against the expected Gmail backend before calling executeHttpsUnsubscribe;
reject mismatches with the existing approval-change error, alongside the
provider, profile, and account checks.

In `@src/mailbox-broker/protocol.ts`:
- Line 13: Align the request-size limit with the schema’s worst-case batch size:
update MAX_REQUEST_BYTES to accommodate valid UniqueMessageRefsSchema batches,
or tighten MessageRefSchema/its batch constraints so mark-read and propose-trash
requests cannot exceed the transport cap. Ensure the chosen limit is enforced
consistently by request parsing and validation.

In `@src/mailbox-broker/server.ts`:
- Around line 76-86: Validate each decoded reference’s backend/provider before
selecting a profile, rejecting v2 references whose claimed profile does not
match the reference backend (including mixed backends in profileFromReferences).
Update profileFromReference and profileFromReferences to perform this validation
before calling selectedProfile, so propose-trash cannot persist
provider-mismatched drafts.

In `@src/providers/email-outlook.ts`:
- Line 77: In the Outlook send logic, update the non-OK response branch in the
relevant method to consume or cancel the response body before throwing the
error. Use the existing response object to call its cancellation method, then
preserve the current statusMessage-based error.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b13b6fe1-1795-412a-a350-0434db002f0f

📥 Commits

Reviewing files that changed from the base of the PR and between e525264 and a7f6f55.

📒 Files selected for processing (39)
  • README.md
  • config.example.yaml
  • docs/hermes.md
  • docs/oauth-onboarding.md
  • docs/smtp-onboarding.md
  • scripts/oauth-setup.sh
  • scripts/smtp-setup.sh
  • skill/SKILL.md
  • src/bot.ts
  • src/config.ts
  • src/executor.ts
  • src/index.ts
  • src/mailbox-broker/adapter.ts
  • src/mailbox-broker/gmail-inbox.ts
  • src/mailbox-broker/gmail-trash.ts
  • src/mailbox-broker/gmail-unsubscribe.ts
  • src/mailbox-broker/outlook-mailbox.ts
  • src/mailbox-broker/profiles.ts
  • src/mailbox-broker/protocol.ts
  • src/mailbox-broker/reference.ts
  • src/mailbox-broker/server.ts
  • src/mailbox-broker/trash-proposal.ts
  • src/mailbox-broker/unsubscribe-proposal.ts
  • src/mailbox-client.ts
  • src/oauth-setup.ts
  • src/oauth/cli-options.ts
  • src/oauth/config-writer.ts
  • src/oauth/outlook.ts
  • src/oauth/persist.ts
  • src/providers/email-outlook.ts
  • src/providers/outlook-token-client.ts
  • src/schema.ts
  • src/smtp-setup.ts
  • src/smtp/cli-options.ts
  • tests/mailbox-profiles.test.ts
  • tests/oauth-setup.test.ts
  • tests/outlook-mailbox.test.ts
  • tests/outlook-provider.test.ts
  • tests/smtp-setup.test.ts

Comment thread src/mailbox-broker/gmail-unsubscribe.ts Resolved
Comment thread src/mailbox-broker/protocol.ts Resolved
Comment thread src/mailbox-broker/server.ts Resolved
Comment thread src/providers/email-outlook.ts Resolved
@404Dealer
404Dealer merged commit 4810766 into master Jul 11, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants