service: inbound mail + calendar sync (open-core scope) — `plugin-email` is outbound-only, so email-to-record is impossible in any app

[os-zhuang]

Current state (verified)

plugin-email is a complete outbound stack and nothing else:

• src/transports/ — smtp.ts, postmark.ts, resend.ts. All send-side.
• Template engine (mustache-style with formula formatters), outbox sweep, queue delivery, attachment storage.

There is no inbound path at all: no IMAP / EWS / Graph client, no mailbox sync loop, no message ingest, no association of a received message to a record. service-calendar does not exist either — apps can render a calendar view over their own event object, but nothing synchronises with an external calendar.

Consequence: "the customer's emails show up on the customer record" cannot be built on this platform today, in any app, by any means short of a bespoke integration per deployment.

Why this belongs in the open core

Found while scoping a bank CRM RFI (VTB Shanghai SME), where it was the single largest technical risk and the critical-path item of phase 1 — quoted at ~60 person-days of custom work. But the reason to put it in core is not that one deal:

• HotCRM is the marketplace flagship and it is demonstrably incomplete without it. Email-to-record is the first thing any CRM evaluator tries. "Requires a custom integration" at that moment ends the evaluation.
• Every comparable open CRM (SuiteCRM, EspoCRM, Odoo) ships inbound mail in its free tier. Gating it would put us behind the free alternatives at exactly the point where a prospect is comparing.
• It is protocol plumbing, not governance. It fails the "the buyer is the IT/compliance function" test that justifies enterprise tier — the person who feels this feature is the end user, every day.

Scope split (agreed): this issue covers the standards-based layer only. Tenant-scale administration — Exchange/Graph tenant-wide delegation, Google domain-wide delegation, bulk mailbox provisioning, sync health monitoring — is enterprise-tier and will be filed separately. Rule of thumb we settled on: one person connecting their own IMAP mailbox is core; taking over 500 Exchange mailboxes at once is enterprise.

Proposed architecture

Three layers, so that the enterprise tier extends rather than forks this work:

1. Connector layer — protocol + auth only, following the existing packages/connectors/ convention (connector-rest, connector-openapi, connector-mcp, connector-slack):

• connector-imap (+ SMTP for the send side already covered by plugin-email)
• connector-caldav
• Enterprise adds connector-exchange / connector-graph / connector-google on the same interface.

2. Service layer — the sync engines, sharing the connector's account + credentials:

• service-mailbox — folder cursors / UID state, incremental fetch, dedup, threading, attachment extraction, bounce & auto-reply suppression.
• service-calendar — event sync, recurrence (RRULE) expansion, timezone correctness, attendee/RSVP state, optional write-back.

They are separate services because the sync semantics genuinely differ (mail is read-mostly; calendar is commonly bidirectional) and a customer may want one without the other — but they share one account and one auth layer, hence the shared connector.

3. Association seam — the part that must NOT live in the platform.

The platform has no business knowing what a "contact" or an "account" is. It should deliver normalised messages/events into platform-level objects and expose an extension point of the shape "given these participant addresses, which record(s) does this belong to?", which the app answers. HotCRM would resolve to crm_contact / crm_account and mount onto its existing crm_event / crm_event_attendee.

This follows the precedent already set by sys_email (a platform-level outbound queue object that apps write into): the inbound mirror would be platform-owned (sys_mail_message, sys_calendar_event), with the app's own business object associated to it rather than replaced by it.

Design decisions to settle

1. Mirror vs. adopt — does the app relate its own event object to the platform's synced event, or does the platform's object become the app's? Mirror avoids forcing every app into one event shape but costs a join and a sync direction.
2. Association timing — resolve at ingest (stamp the link) or at read (resolve dynamically)? Ingest is faster to read and survives contact-record changes badly; read-time is the reverse.
3. Unmatched messages — drop, or keep in an unassociated pool for later matching when the contact is created? (CRM users expect the latter.)
4. Shared vs. per-user mailboxes — the lightweight pattern (one dedicated mailbox that users forward or BCC into, parsed and associated) is materially cheaper than per-user sync and covers a lot of real demand. Worth shipping first; it is also what we scoped as the phase-1 fallback on the RFI above.
5. Privacy posture — syncing a user's whole mailbox into a shared CRM is a real concern in some jurisdictions. Need a declarable policy (folder allowlist, participant-must-be-a-known-contact, explicit per-message share).

Implementation will likely split into sub-issues per connector and per service; filing as one issue so the layering and the seam get designed once rather than twice.

Verified against

0f539bd — packages/plugins/plugin-email/src/ (transports, template-engine, outbox-sweep), packages/connectors/, packages/services/.

[os-project-manager]

Triage: needs-user-decision + domain:services + type Feature — human floor twice over (new capability class; multi-week programme needing appetite). target:v18 kept as filed: this is v18 planning scope, not a current-release blocker. The five design decisions in the body are genuine product semantics (mirror-vs-adopt, association timing, unmatched pool, mailbox topology, privacy posture) — none is triage-adjudicable.

Four-axis card face

1. Platform long-term coherence: the three-layer split (connector / sync service / association seam) follows the existing packages/connectors/ convention, and the seam keeps "what is a contact" out of the platform — contract-first, enterprise extends rather than forks. The sys_email outbound precedent gives the inbound mirror (sys_mail_message) a shape that already exists.
2. Measured business pull: strongest axis — a live bank-CRM RFI where this was the single largest risk (~60 person-days quoted), plus the marketplace flagship (HotCRM) failing the first thing every CRM evaluator tries. Comparable open CRMs all ship inbound mail free; the open-core placement argument is concrete, not speculative.
3. AI-agent error-resistance: platform-owned normalized objects + one closed extension point ("which record(s) do these participants belong to?") is structurally harder to misuse than per-app bespoke IMAP ingest; the privacy posture must be a declarable closed policy (folder allowlist / known-contact / per-message share), not runtime tolerance.
4. Startup scope discipline: the counterweight — 2 connectors + 2 services + a seam is the largest programme in the inbox. The card's own decision 4 names the disciplined first slice: one shared mailbox (forward/BCC-in), parsed and associated covers most real demand at a fraction of per-user sync cost.

Recommendation: approve the direction and layering, but appetite-gate phase 1 to the shared-mailbox pattern + association seam + sys_mail_message only; per-user IMAP sync, CalDAV, and write-back become Blocked-by:-chained sub-issues after the seam proves out (contract-first split, one sub-issue per layer, spec-facing object shapes routed to the spec seat). The five design decisions need maintainer answers before any spec work starts.

Dependency flag: no open card carries a Blocked-by: pointing here today.

Triage: this comment comes from the triage seat Routine; not a claim.

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling (2026-08-17, recorded by PM session session_01NYgmGheCzM6NrHZN436Cxf). The maintainer held the dedicated design round on this card, approved the direction and all five design decisions per the PM analysis, and deliberately scheduled the work for v18. Verbatim: 「同意，请记录你的分析结论，但是这个任务我刻意标了 v18，暂时不做。」

This comment is the design record — written so the v18 implementer needs no chat context.

Confirmed: direction, placement, architecture

• Open-core placement confirmed. Inbound mail is category table-stakes (every free-tier competitor ships it; email-to-record is the first thing every CRM evaluator tries), protocol plumbing not governance. The core/enterprise boundary stands as filed: one person connecting their own IMAP mailbox is core; taking over 500 Exchange mailboxes at once is enterprise (tenant-scale delegation, bulk provisioning, sync health = enterprise, filed separately).
• Three-layer architecture confirmed: connector (protocol + auth, packages/connectors/ convention) / sync services (service-mailbox, service-calendar — separate engines, shared account+credentials) / association seam (the platform never learns what a "contact" is; one closed extension point — "given these participant addresses, which record(s)?" — answered by the app).
• Phase 1 scope: shared mailbox (forward/BCC ingest) + association seam + sys_mail_message, only. Per-user IMAP sync, CalDAV/calendar entirely, write-back, and the enterprise admin plane are all Blocked-by:-chained follow-ups. Calendar is deferred wholesale (bidirectional = harder, zero measured pull today).

The five design decisions — ruled

1. Mirror, not Adopt. Platform owns faithful mirror objects (sys_mail_message, sys_calendar_event) whose schema is dictated by the external standards (RFC 5322 / iCalendar); apps keep their own business objects (crm_event etc.) linked by a declared association. Rationale on record: a mirror row and a business row carry two different truths ("what the external system says" vs "what the business recorded") — Adopt forces them into one object where sync semantics and business semantics collide (external deletion vs business retention; engine re-sync/dedupe vs app-written fields; every new app category renegotiating one shared shape). Mirror keeps sync mechanical and business free; it is sys_email's proven shape, inbound. Under the AI-error axis it is decisive: Adopt invites AI authors to extend sys_* objects with business keys — the ungoverned platform-object-row surface #9054 measured; Mirror gives them a closed contract. Accepted costs: one indexed join on timelines; write-back (later) becomes an explicit opt-in projection rather than an accidental side effect.

2. Association stamped at ingest + an explicit re-match action — not read-time dynamic resolution. Timelines stay stable, attribution is a deterministic auditable fact (the compliance narrative of the regulated-market direction), and the RFI's 2s record-open budget survives. Contact-created-later / contact-changed cases are handled by the explicit re-match mechanism shared with decision 3 — state is declared, changes are recorded.

3. Unmatched messages go to an unassociated pool, retro-matched when a contact is created — never dropped (prospect-mails-first is the normal sales sequence). Pool visibility defaults restricted (mailbox admins/owners only, not org-wide) — the pool is the card's most privacy-sensitive corner.

4. Shared mailbox first — it is phase 1. The connector interface is designed now for the per-user shape (account + credential abstraction); phase 1 is its first implementor, so per-user later extends rather than rewrites.

5. Privacy: "forwarding is consent" is phase 1's declared semantic. The full declarable policy vocabulary (folder allowlist / participant-must-be-known-contact / per-message share) lands with the per-user phase, where the hard privacy surface actually lives — as closed declarable keys, never runtime tolerance. Design note pinned: the known-contact switch is semantically opposed to the unmatched pool (one rejects stranger mail, the other exists for it) — it must be an opt-in strictness knob, default OFF; the two must not both be defaults.

Status: pm:on-hold — deliberately not now

• Date: 2026-08-17. Reason: the maintainer deliberately scheduled this at v18 (「刻意标了 v18，暂时不做」); nothing is dispatched and no sub-cards are carved yet.
• Named restart condition: the v18 planning window opens (v18 board work begins). On restart, this card becomes the parent/coordination node (never dispatched itself) and carves per the plan above: connector-imap · minimal service-mailbox (shared-mailbox ingest, parse, dedupe, attachments) · association seam + sys_mail_message (spec accept-surface addition ⇒ spec seat, claude-fable-5), plus Blocked-by: placeholder cards for per-user IMAP / CalDAV / write-back / enterprise admin plane.
• target:v18 and domain:services stay.

Labels flipped needs-user-decision → pm:on-hold in the same stroke.

---

Generated by Claude Code