Skip to content

feat: email inbox foundation via JMAP (spec 01) - #24

Merged
fclairamb merged 9 commits into
mainfrom
feat/email-inbox-jmap
May 2, 2026
Merged

feat: email inbox foundation via JMAP (spec 01)#24
fclairamb merged 9 commits into
mainfrom
feat/email-inbox-jmap

Conversation

@fclairamb

@fclairamb fclairamb commented May 2, 2026

Copy link
Copy Markdown
Owner

Summary

  • New internal/jmap package: minimal JMAP (RFC 8620 / 8621) client + long-running inbox manager.
  • Three super-admin endpoints: GET /system/email-inbox/status, POST /system/email-inbox/test, POST /system/email-inbox/sync.
  • Manager idle-loops when email_inbox system parameter is missing/disabled; supports EventSource (with reconnect) or polling fallback; multi-handler chain (first non-Ignored outcome wins) so spec 02 can plug in.

Spec

First todo from the email-inbox series (specs/todos/2026-04-29-01-email-inbox-jmap.md, archived to specs/done/2026/04/). Spec 02 will register the email-check handler.

Scope

  • ~2,200 LOC across types/client/methods/eventsource/manager/system handler/wiring/tests.
  • No DB migrations, no public API surface beyond the three system endpoints.
  • Idle when not configured — landing this PR is safe even with no JMAP server set up.

Test plan

  • make build-backend lint-back test clean
  • Unit tests cover client/methods/eventsource/manager + status
  • CI green on this PR
  • Verification flow from the spec works against a real JMAP server (manual, post-merge)

Generated with Claude Code

fclairamb and others added 9 commits May 2, 2026 02:50
@fclairamb
chore: start implementing Email Inbox via JMAP — Foundation
2354090
@fclairamb
docs: add implementation plan for Email Inbox via JMAP — Foundation
3ea3331
@fclairamb @claude
feat: add JMAP types and client for inbox plumbing
c1c5a1f 
Step 1 of the email-inbox-jmap spec: minimal JMAP (RFC 8620 / 8621) types
and HTTP client. Covers session discovery, the `Request` / `Response`
envelope wire format ([name, args, clientID] tuples), Email/Mailbox/
EmailAddress/EmailHeader/Attachment/ChangesResponse domain types, and a
basic-auth `Client` with `DiscoverSession` and `Call`. Includes
`Config.ApplyDefaults` and a rewrite-base mechanism for proxied setups.

Tests: round-trip MethodCall/MethodResponse JSON, session discovery
against an httptest server (success, missing mail account, proxy
rewrite), and Call envelope/response handling.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@fclairamb @claude
feat: add typed JMAP method wrappers (Mailbox + Email)
15984d7 
Step 2 of the email-inbox-jmap spec: typed wrappers over Client.Call —
MailboxQuery, MailboxGet, FindMailboxByName, FindMailboxByRole,
FindOrCreateMailbox, EmailQuery (with InMailbox/Before/NotInMailbox
filter), EmailGet, EmailSetMailbox (move via mailboxIds/<id> patch
notation per RFC 8621 §4.6), EmailDestroy, EmailChanges.

Errors are wrapped sentinels — ErrMailboxNotFound, ErrMailboxNotCreated,
ErrEmptyResponse, ErrParseResponse, ErrPartialUpdate, ErrPartialDestroy.
Callers test with errors.Is.

Tests cover each method against an httptest fixture server that returns
canned method responses keyed by method name.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@fclairamb @claude
feat: add JMAP EventSource SSE listener with reconnect
c5e576f 
Step 3 of the email-inbox-jmap spec: Server-Sent Events listener for
the JMAP eventSourceUrl (RFC 8620 §7.3). Hand-rolled SSE parser (no
third-party dep) handles `event:`/`data:` field accumulation, comment
lines (`:` keepalive pings), and blank-line event termination.
ListenEventSourceWithReconnect runs until ctx cancellation, with
exponential backoff (1s → 5min cap) reset on successful connect.

Tests: state events dispatched (filtering pings is the handler's job —
the listener delivers everything tagged event:state); reconnect after
the server drops a connection.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@fclairamb @claude
feat: add JMAP inbox manager (supervisor + handler chain)
0592eba 
Step 4 of the email-inbox-jmap spec: long-running supervisor that
loads the email_inbox system parameter, discovers the JMAP session,
resolves Inbox/Processed/Trash mailboxes (creating Processed when
absent), and dispatches sync work via either EventSource or polling.

Public API:
- Manager.Run(ctx) — supervisor loop, blocks until ctx done
- Manager.RegisterHandler(h) — register before Run; first non-Ignored
  outcome wins
- Manager.GetStatus() — connected, lastSyncedAt, lastError, accountId
- Manager.TriggerSync(ctx) — non-blocking, coalesces via depth-1 chan
- Manager.TestConnection(ctx, cfg) — used by the admin test endpoint

EventSource path filters duplicate Email-state events (only triggers
sync on actual state changes, not pings or unrelated state). Polling
path runs an immediate sync then ticks every PollIntervalSeconds.

Cleanup loop runs hourly: Processed/Inbox older than retention →
Trash; Trash older than 7 days → destroy.

Tests use a small in-process fake JMAP server: two-handler routing
(Ignored, Processed) drives the move-to-Processed path; status
captures last error; TestConnection succeeds end-to-end.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@fclairamb @claude
feat: wire JMAP inbox manager into system handler and server
2a2fc0a 
Steps 5 + 6 of the email-inbox-jmap spec.

system handler:
- New error codes EMAIL_INBOX_{NOT_CONFIGURED,DISABLED,TEST_FAILED,
  NOT_AVAILABLE} in handlers/base.
- system.Service gains an injectable JMAPInboxManager interface so the
  handler is decoupled from the concrete *jmap.Manager.
- New service methods: EmailInboxStatus, EmailInboxTest (uses stored
  config when no override), EmailInboxSync (returns disabled if cfg is
  off, not-configured if missing).
- Three handler methods + matching routes:
    GET  /api/v1/system/email-inbox/status
    POST /api/v1/system/email-inbox/test
    POST /api/v1/system/email-inbox/sync
  All under the existing super-admin middleware chain.

server wiring:
- Server gains a `jmapManager *jmap.Manager` field constructed in
  setupRoutes and started in Start() against runnerCtx, so the
  supervisor outlives a single request and shuts down with the
  service. The goroutine is tracked in workersWg.
- Spec 02 will append `inboxManager.RegisterHandler(...)` here.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@fclairamb
chore: all checks passing for Email Inbox via JMAP — Foundation
d4fcdea
@fclairamb
docs: archive completed spec Email Inbox via JMAP — Foundation
e3b44f1
@fclairamb
fclairamb enabled auto-merge (squash) May 2, 2026 01:22
@fclairamb
fclairamb merged commit 0f3b0c1 into main May 2, 2026
11 checks passed
@fclairamb
fclairamb deleted the feat/email-inbox-jmap branch May 2, 2026 01:27
@fclairamb fclairamb mentioned this pull request May 2, 2026
Merged
fclairamb added a commit that referenced this pull request Jun 23, 2026
@fclairamb
chore(release): v0.1.0 (#4)
3cd305f 
🤖 I have created a release *beep* *boop*
---


##
[0.1.0](v0.0.0...v0.1.0)
(2026-06-22)


### Features

* add check type registry, sample configs, notification senders, and
observability integrations
([eea049e](eea049e))
* batch — Warning/Degraded statuses, SSL/Docker check upgrades, MCP
OAuth 2.1, config-as-code
([#85](#85))
([936d830](936d830))
* batch spec implementations (dashboard UI, jobs, notifications, SaaS,
perf) ([#78](#78))
([fe003e4](fe003e4))
* bulk feature integration (discovery, web push, badges, webhooks, and
more) ([#73](#73))
([a976856](a976856))
* custom user-agent, refresh checks, vite plugin switch, CI updates
([#1](#1))
([cc00858](cc00858))
* documentation site served at /docs (co-located in web/docs)
([#88](#88))
([27d9ccd](27d9ccd))
* email check frontend (spec 03)
([#30](#30))
([aebd106](aebd106))
* email inbox foundation via JMAP (spec 01)
([#24](#24))
([0f3b0c1](0f3b0c1))
* email passive checks (spec 02)
([#27](#27))
([ba5536f](ba5536f))
* **entitlements:** trim to MaxSSOUsers + MaxChecksPerMinute + status
page history fixes
([#50](#50))
([a007de0](a007de0))
* **entitlements:** trim to MaxSSOUsers + MaxChecksPerMinute, enforce
both ([#49](#49))
([d25cc5f](d25cc5f))
* group incident correlation (spec 04 backend v1)
([#31](#31))
([1883986](1883986))
* **observability:** instrument hot path + add bench harness
([#60](#60))
([c6604cc](c6604cc))
* **oncall:** searchable timezone dropdown + sidebar logo polish
([#46](#46))
([4396898](4396898))
* per-IP HTTP rate limiting and concurrency limiting
([#59](#59))
([f9cc273](f9cc273))
* soften HTTP rate limits with bounded queues + request timeout
([#63](#63))
([025501b](025501b))
* SolidPing — distributed uptime monitoring platform
([eef4383](eef4383))
* **statuspages:** drag-and-drop resource reordering + dash conventions
([#41](#41))
([cf910d4](cf910d4))


### Bug Fixes

* **deps:** update dependency i18next to v26
([#26](#26))
([d5d1b7e](d5d1b7e))
* **deps:** update dependency lucide-react to v1
([#28](#28))
([cdc8e8c](cdc8e8c))
* **deps:** update dependency react-i18next to v17
([#29](#29))
([13135d8](13135d8))
* **deps:** update dependency recharts to v3.8.1
([#14](#14))
([5d95a3b](5d95a3b))
* **deps:** update go dependencies (non-major)
([#16](#16))
([2450f13](2450f13))
* **deps:** update go dependencies (non-major)
([#19](#19))
([f842310](f842310))
* **deps:** update go dependencies (non-major)
([#37](#37))
([c020eca](c020eca))
* **deps:** update go dependencies (non-major)
([#44](#44))
([ff0bcd0](ff0bcd0))
* **deps:** update go dependencies (non-major)
([#52](#52))
([2e3bc28](2e3bc28))
* **deps:** update go dependencies (non-major)
([#69](#69))
([a65ed4c](a65ed4c))
* **deps:** update go dependencies (non-major)
([#77](#77))
([a0920ff](a0920ff))
* **deps:** update go dependencies (non-major) to v1.4.2
([#86](#86))
([1eb7504](1eb7504))
* **deps:** update module github.com/aws/aws-sdk-go-v2/config to
v1.32.18 ([#72](#72))
([6406537](6406537))
* **deps:** update module github.com/aws/aws-sdk-go-v2/service/s3 to
v1.101.0 ([#39](#39))
([f9c9563](f9c9563))
* **deps:** update module github.com/go-webauthn/webauthn to v0.17.3
([#45](#45))
([593931a](593931a))
* **deps:** update module github.com/go-webauthn/webauthn to v0.17.4
([#70](#70))
([fca1c97](fca1c97))
* **deps:** update module github.com/ibm/sarama to v1.48.1
([#47](#47))
([93ccf3a](93ccf3a))
* **deps:** update module github.com/ibm/sarama to v1.48.2
([#54](#54))
([e84d868](e84d868))
* **deps:** update module github.com/ibm/sarama to v1.49.0
([#64](#64))
([fd61bd7](fd61bd7))
* **deps:** update module github.com/oapi-codegen/runtime to v1.4.1
([#65](#65))
([a3a3e9f](a3a3e9f))
* **deps:** update module github.com/prometheus/common to v0.67.5
([#61](#61))
([095dd6f](095dd6f))
* **deps:** update module github.com/slack-go/slack to v0.24.0
([#75](#75))
([6e86d5b](6e86d5b))
* **deps:** update module golang.org/x/sys to v0.44.0
([#42](#42))
([a245730](a245730))
* **deps:** update module golang.org/x/sys to v0.45.0
([#67](#67))
([49c3d90](49c3d90))
* **deps:** update module golang.org/x/term to v0.43.0
([#43](#43))
([4a934f1](4a934f1))
* **deps:** update module google.golang.org/grpc to v1.81.0
([#36](#36))
([1be183a](1be183a))
* **deps:** update module google.golang.org/grpc to v1.81.1
([#55](#55))
([6bfac2d](6bfac2d))
* status lifecycle improvements and created/running result handling
([#5](#5))
([fc64c7d](fc64c7d))
* **status0:** white page header and de-duplicated footer
([#48](#48))
([77506a7](77506a7))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).
This was referenced Sep 8, 2026
Closed
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

automerge

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@fclairamb