MAIL-001 consolidated job-email hub

Updated: 2026-08-10

Status: IN PROGRESS. Canonical hub routing, provider-neutral reads, explicit-confirmed send API and editable reply UI are implemented and locally verified; recovery, legacy-send and remaining provider actions remain.

Revalidated current boundaries

/correspondence listed persisted, job-linked Correspondence rows with search/direction/link filters.
/correspondence/review separately rendered Gmail review candidates/suggested jobs and linked back to the inbox.
The job workspace already embeds the shared Correspondence component and therefore reads/writes the same underlying rows rather than a copy.
Gmail review decisions, import/link/unlink/relink and job creation use existing Gmail APIs. Outlook/Graph and IMAP connection models exist, but this review surface is Gmail-specific.
The per-job composer currently logs a message to Correspondence; it is not a provider-send draft flow. Separate follow-up sending exists elsewhere and must not be mislabeled or silently reused.

Implemented first increment

/correspondence is the canonical Job email hub with linked-message and recruitment-suggestion views represented by ?view=review.
The review component embeds under the hub with correct heading hierarchy and without duplicate back navigation.
/correspondence/review remains a compatibility route and redirects to the canonical filtered hub.
Switching to review does not issue the linked-correspondence query; switching views reuses the existing tested review component and APIs.
No provider connection, sync, import, link or send behavior changed.

Implemented provider-neutral read increment

Added one authenticated /api/email controller over the existing IEmailProviderRegistry for provider status, search, thread summaries and plain-text message detail.
Every operation passes the authenticated owner ID into the registered Gmail, Outlook or IMAP adapter and rejects unknown or disconnected providers before mailbox access.
Message detail intentionally omits provider HTML. Untrusted provider markup is not exposed through this shared endpoint.
The hub now identifies connected and disconnected providers and advertises their actual capability. Gmail, Outlook and IMAP are currently shown as read-only because their installed scopes/contracts do not implement provider send.
The controller does not change OAuth scopes, connect accounts, invoke providers in tests or claim that the legacy SMTP follow-up sender is provider-native.

Implemented safe message-detail increment

Provider-backed rows now open plain-text detail through /api/email/message; the UI never renders provider HTML.
If a provider is disconnected or unavailable, the hub clearly warns and shows the owner-scoped saved JobTracker copy instead of losing access to imported correspondence.
Manual/internal rows use the same detail shape through /api/correspondence/message/{id}.
Direct saved-message IDs remain tenant-filtered. Malformed legacy label/attachment JSON degrades to empty metadata instead of breaking the message view.
Rapid selection changes invalidate older requests so late provider responses cannot appear under the wrong message.
Inbox label and attachment counts now reflect parsed metadata arrays rather than treating every non-null JSON field as one item.

Implemented inert send-ledger increment

Added tenant-owned EmailSendAttempts with pending/sending/sent/failed/uncertain states and a unique owner/client-request key.
A request ID can be reused only for the same SHA-256 payload hash. Different content under an old request ID is rejected.
Only pending attempts may enter sending, and only sending attempts may become terminal. Failed or uncertain attempts cannot be restarted blindly.
The ledger stores provider/idempotency/status/timing metadata only; recipient, subject and message body are intentionally absent.
Deleting the owning job cascades the ledger row. The global owner filter protects direct attempt IDs.
The additive migration has provider-specific SQLite/MariaDB types and reversible up/down SQL. No send route, OAuth scope or provider call was enabled.

Implemented provider-delivery adapter increment

Gmail and Microsoft Graph authorization URLs now request explicit send consent in addition to read access. Existing read-only connections remain read-only until the user reconnects.
Provider status derives send capability from the stored granted scope. IMAP remains read-only because it has no configured outgoing transport.
Gmail builds an RFC MIME plain-text message, supports the existing Gmail thread ID, and uses the documented send endpoint. Graph sends plain-text JSON through sendMail.
HTTP rejection is a known failed-before-delivery category; 401/403 requires reauthorization. Network interruption/cancellation is marked uncertain because acceptance cannot be disproved.
Provider response bodies and transport exception details are not returned to callers. Recipient/body fixtures and HTTP transport are synthetic/mocked; no provider was contacted.
The adapters are reachable only through the later explicit-confirmed API; no JobTracker send button exists yet.

Implemented explicit-send API increment

Added one authenticated, rate-limited POST /api/email/send route. It requires an owned job, a send-capable connected provider, an explicit confirmed=true, and valid bounded recipient/subject/body/thread fields.
Client UUIDs are canonicalized before the tenant ledger reservation. Reusing a UUID with different content is rejected; sent duplicates return the original result; pending, failed or uncertain attempts are never redelivered automatically.
The ledger is reserved and moved to sending before provider I/O. Provider rejection is failed, transport ambiguity is uncertain, and connection failure before delivery is failed.
Successful delivery writes the outbound correspondence, a content-free job event and the ledger terminal state in one local database transaction. Provider acceptance followed by local persistence failure is surfaced as uncertain.
The audit event and ledger omit recipient, subject and body. Full content exists only in the intended job correspondence record.
Tests use owner-isolated SQLite and a fake provider; no email, OAuth flow, provider service or external network was invoked.

Verification

Focused delivery/provider/capability: 18/18; send ledger: 3/3; provider/correspondence controllers: 5/5; hub detail: 5/5.
Explicit-send controller/store/read focused tests: 12/12.
Confirmed composer focused tests: 7/7.
Full backend: 619/619; full frontend: 49/49 suites, 190/190 tests.
Production build/TypeScript and git diff --check: pass.
Implementation commits: 6008b4a, 536d403, a20775c, 653f011, e9937ac, 123fc55, 449faeb.

Implemented editable composer increment

Provider-backed message detail offers Reply only when that exact connected provider has send consent. Read-only connections show an explicit reconnect requirement; manual correspondence is not mislabeled as provider-send capable.
Recipient, subject, thread, provider/from account and body remain visible before sending. Recipient, subject and body remain editable; the provider and provider thread remain fixed to avoid cross-provider thread claims.
The app-owned confirmation dialog identifies provider/from address, recipient, subject and thread. Cancelling leaves the draft intact and invokes no API.
One UUID remains stable through pre-send edits. A failed attempt requires an explicit new attempt; an uncertain/pending/sending result disables retry and tells the user to inspect the provider Sent folder.
A network/unknown server interruption is treated as uncertain on the client. Successful sends refresh the same correspondence domain; no second copy or autonomous AI/send path was added.
Draft state is in-memory for this increment. Navigation within the hub preserves it, but refresh persistence and compose-new-message flow remain separate work.

Remaining MAIL-001 work

Extend shared provider-neutral thread navigation and application embedding while preserving provider capability differences.
Surface provider identity, reauthorization, read/unread, pin/read-later/archive/spam/trash only where the provider supports it.
Share thread detail and link/unlink actions between hub and job workspace.
Add durable draft/refresh recovery and compose-new-message behavior if confirmed by the remaining workflow inventory; replies are implemented.
Reconcile abandoned sending attempts to an explicit uncertain/manual-review state after process failure; never auto-resend them.
Include non-sensitive send-attempt metadata in user export and verify account/job deletion coverage before production rollout.
Preserve minimal audit metadata without sensitive body logging; verify Free non-AI access and Pro-only AI assistance.
Complete link/unlink/dismiss/draft/send/failure/two-user/application-embed tests plus browser/production provider gates. No real email may be sent during repository verification.

Validation limitation

The first focused Jest invocation exhibited the repository's open-handle delay. The passing focused and full runs used --forceExit; the full run took 228.709 seconds. A Next build process also failed to exit after compilation; only the exact PIDs started by those build attempts were stopped, then a clean build completed. This is recorded as tooling/runtime behavior, not hidden.

Rollback

Disable the UI/admission path before rollback. Revert 123fc55 to remove the send route, then e9937ac for send consent/adapters and 653f011 (after migration downgrade) for the ledger, followed by earlier read/routing commits. Existing provider grants are not revoked by a code rollback; disconnect/reconnect is an explicit user action.

9.7 KiB Raw Blame History