jmap-webmail/ROADMAP.md

JMAP Webmail - Roadmap

This document tracks the development status and planned features for JMAP Webmail.

Completed Features

Core Infrastructure

• Next.js 16 with TypeScript and App Router
• Tailwind CSS v4 with Oxide engine
• Zustand state management
• Custom JMAP client implementation (RFC 8620)

Authentication

• Login with JMAP server authentication
• Session management (no password storage for security)
• Username autocomplete with history
• Logout functionality
• Authentication error handling
• JMAP identities for sender address
• TOTP two-factor authentication (Stalwart-compatible)
• OAuth2/OIDC with PKCE (opt-in SSO, session persistence, RP-initiated logout)
• External IdP support via explicit issuer URL (Keycloak, Authentik, etc.)
• "Remember me" session persistence for Basic Auth (AES-256-GCM encrypted httpOnly cookie)
• OAuth-only mode (OAUTH_ONLY env var to hide basic auth form)

JMAP Server Connection

• Session establishment and keep-alive
• Connection error handling and retries
• CORS error detection with actionable user guidance
• Session URL origin rewriting (fixes Docker/reverse proxy deployments where server returns internal hostname)
• Storage quota display
• Server capability detection
• Shared folders support (multi-account access)

Email Operations

• Email fetching and display
• Full HTML email rendering
• Compose, reply, reply-all, forward
• Draft auto-save with discard confirmation
• Mark as read/unread
• Star/unstar emails
• Delete and archive
• Color tags/labels
• Full-text search
• Advanced search with JMAP filter panel, search chips, and cross-mailbox queries
• Attachment upload and download
• Batch operations (multi-select with shift-click, batch move/delete toolbar)
• Quick reply form
• Email threading (Gmail-style inline expansion)

Real-time Updates

• EventSource for JMAP push notifications
• State synchronization
• Email arrival notifications
• Real-time unread counts
• Mailbox change handling

User Interface

• Three-pane layout (sidebar, list, viewer)
• Minimalist design system
• Dark and light theme support
• Custom scrollbars
• Mobile responsive design
• Keyboard shortcuts
• Drag-and-drop email organization
• Right-click context menus
• Hierarchical mailbox display
• Folder management (create, rename, move, delete via context menu, drag-and-drop reparenting)
• Email list with avatars and visual hierarchy
• Expandable email headers
• External content warning banner
• SPF/DKIM/DMARC status indicators
• Loading states and skeletons
• Smooth transitions and animations
• Infinite scroll pagination
• Virtual scrolling for large email lists
• Error boundaries
• Settings page with preferences
• Navigation rail (desktop vertical icon sidebar + mobile bottom tab bar)
• Welcome banner for first-time users (one-time display, localStorage persistence)
• Confirmation dialog component with promise-based useConfirmDialog hook
• Toast notifications with undo action support and typed durations
• Inline form validation with shake animation (email composer, contact form)
• Login UX polish (error shake, discreet 2FA toggle, password visibility toggle, session expired banner)
• Empty state patterns for contacts (distinct "no data" vs "no search results" with contextual actions)
• WCAG AA reduced-motion media query (global animation/transition reset)
• Safe area inset utilities for notched devices
• Screen reader live region announcements (sr-only)

Internationalization

• English language support
• French language support
• Japanese language support
• Spanish language support
• Italian language support
• German language support
• Dutch language support
• Portuguese language support
• Automatic browser language detection
• Language preference persistence

Security & Accessibility

• External content blocked by default
• HTML sanitization with DOMPurify
• User control for loading external content
• Trusted senders list for automatic image loading
• Dark mode email readability (intelligent color transformation)
• WCAG 2.0 Level AA color contrast compliance
• Newsletter unsubscribe support (RFC 2369)
• XSS attack prevention with comprehensive validation
• CSP Report-Only headers with per-request nonce
• Security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy)
• Reusable focus trap hook (Tab cycling, Escape handling, focus restore)
• WCAG AA prefers-reduced-motion support (global animation/transition reset)
• Safe area insets for notched mobile devices
• Screen reader sr-only live region for dynamic announcements

Identity Management

• Multiple sender identities (name, email, signature)
• Sub-addressing support (user+tag@domain.com)
• Per-identity signatures
• Identity badges in email viewer and list
• Tag suggestions based on context
• Display name included in From header (recipients see name, not just email)
• Primary identity (matching login) selected by default in composer

Address Book & Contacts

• Contact store with JMAP sync and local fallback
• Contact CRUD operations (create, read, update, delete)
• Contacts list view with search/filter
• Contact details view/edit form
• JMAP contacts sync (RFC 9553/9610 ContactCard/AddressBook)
• Email autocomplete from contacts
• Contacts integration in email composer (To/Cc/Bcc)
• Contact groups/lists management with JMAP members map
• vCard import/export (RFC 6350 parser/generator, duplicate detection)
• Bulk contact operations (multi-select, delete, group add, export)
• i18n support for contacts (all 8 languages)

Vacation Responder

• JMAP VacationResponse singleton management
• Settings tab with date range and message configuration
• Sidebar indicator when vacation auto-reply is active
• i18n support (all 8 languages)

Calendar Integration

• JMAP Calendar types (RFC 8984) and client methods
• Calendar capability detection (urn:ietf:params:jmap:calendars)
• Calendar store with Zustand (persist middleware)
• Month, week, day, and agenda views
• Event modal (create/edit/delete with recurrence, reminders)
• Mini-calendar sidebar with calendar visibility toggles
• Calendar settings (default view, week start, time format)
• Multi-day event spanning across all covered days
• Column-based overlap layout for concurrent events
• Locale-aware date formatting via next-intl
• First day of week and time format settings wired to views
• Push notification handling for calendar state changes
• Calendar page capability check (redirect if unsupported)
• Error handling with toast feedback on event CRUD
• Timezone auto-detection on event creation
• Input validation, color sanitization, focus trap
• ARIA grid roles and event card accessible labels
• Mobile touch targets (44px minimum)
• Calendar keyboard shortcuts (m/w/d/a views, t today, n new event)
• i18n support with ICU pluralization (all 8 languages)
• Drag-and-drop event rescheduling (week/day time snap, month date move)
• iCalendar (.ics) file import via CalendarEvent/parse with preview and bulk create
• Event notifications with client-side alert evaluation and toast display
• Notification sound, acknowledged alert persistence (localStorage), proactive 24h event fetch
• Configurable notification settings (enable/disable, sound toggle)
• Participant scheduling with iTIP invitations (organizer/attendee UI, RSVP buttons, contact autocomplete)
• Inline calendar invitation banner in email viewer (auto-detect .ics attachments, RSVP, import to calendar, cancellation display)
• Scheduling message support (sendSchedulingMessages flag for create/update/delete)
• Click-drag to create events (pointer-based time range selection, 15-min snap, visual overlay)
• Event resize by dragging bottom edge handle (15-min snap, optimistic JMAP update)
• Recurring event edit/delete scope dialog (this event / this and following / all events)
• Double-click quick event creation (inline title input, PT1H default)
• Event duplication button in modal (clones event +1 day, opens for editing)

Email Filters

• JMAP Sieve Scripts (RFC 9661) with capability detection
• Visual rule builder (conditions: From/To/Cc/Subject/Header/Size/Body, actions: Move/Copy/Forward/Mark read/Star/Label/Discard/Reject/Keep/Stop)
• Raw Sieve script editor with syntax validation
• Sieve generator and parser with JSON metadata round-trip
• Filter store with CRUD, reorder, toggle, auto-save with rollback
• Opaque script detection with reset to visual builder option
• Focus trap accessibility in modals
• Toast validation feedback for empty rules
• Push notification handling for SieveScript state changes
• i18n support (all 8 languages)

Email Templates

• Reusable email templates with local storage persistence
• Category organization (General, Business, Personal, Support, Follow-up, custom)
• Dynamic placeholder variables with auto-fill from composer context
• Template manager modal (create, edit, duplicate, delete)
• Template picker in composer toolbar with search and category filter
• Custom placeholder prompt on template insertion
• Settings tab for template management
• Keyboard shortcut (Ctrl+Shift+T to insert template)
• i18n support (all 8 languages)

Email Display

• Proper email layout without horizontal scroll or clipping
• Blocked image container collapsing (no empty spaces in newsletters)
• Sandboxed iframe rendering for rich HTML emails (CSS isolation from app)
• Adaptive rendering: iframe for complex HTML, inline for plain text/simple HTML
• SPF/DKIM/DMARC tooltips with plain-language security explanations
• Expandable sender info panel (contact lookup, add-to-contacts, search sender)

Mobile & Touch

• Bottom action bar for email actions (Reply, Reply All, Archive, Delete, More)
• Long-press context menu with haptic feedback (300ms, cancels on scroll)
• Touch-friendly context menu submenus (tap-to-expand on touch devices)
• CSS-first responsive layout (instant orientation changes, no JS-driven blink)
• Click-to-toggle more-actions dropdown (was hover-only)

Sidebar & Density

• Tag counts section with color-coded tags and email counts
• Empty folder option for Junk/Trash (batch delete with progress)
• Extra-compact density option (28px rows, 44px on touch devices)
• Resizable sidebar via drag handle (180-400px, keyboard accessible, persisted)

API Robustness

• Exponential backoff retry for transient JMAP failures (429, 502, 503, 504)
• Opt-out for blob downloads, uploads, and polling (no double-request risk)

Testing

• Unit tests for validation utilities (57 tests)
• Unit tests for email sanitization (27 tests)
• Unit tests for color transformation (40 tests)
• Unit tests for contact store (56 tests)
• Unit tests for JMAP contact client (41 tests)
• Unit tests for vCard parser (18 tests)
• Unit tests for thread utilities (20 tests)
• Unit tests for email headers (39 tests)
• Component tests (contacts, UI components — 41 tests)
• JMAP client method tests (identity: 20, contacts: 41)
• Unit tests for Sieve generator (50 tests)
• Unit tests for Sieve parser (14 tests)
• Unit tests for calendar alerts (36 tests)
• Unit tests for calendar notification store (8 tests)
• Unit tests for calendar invitation parsing (25 tests)
• Unit tests for calendar participants (26 tests)
• Unit tests for template utilities (48 tests)
• Unit tests for OAuth PKCE and discovery (14 tests)
• Unit tests for iframe rendering detection (12 tests)
• Unit tests for API retry with backoff (9 tests)
• 704 tests total across 28 test suites
• XSS attack vector testing
• Playwright E2E framework setup

Deployment

• Runtime environment variables (Docker-friendly configuration)
• Health check endpoint
• Docker support (multi-stage build, docker-compose, standalone output)
• Structured server-side logger (text/JSON format, configurable level)
• Pre-built Docker image on Docker Hub and GHCR with multi-arch support (amd64/arm64)
• GitHub Actions CI/CD for automated image publishing on releases
• CVE remediation: remove npm from production image, upgrade Alpine packages
• Server-side update check (logs newer version availability on startup)
• Docker major version tag (jmap-webmail:1) for deployments pinning to major

Release 1.5.0 (2026-04-17)

• Archive action applies to the entire conversation thread (#49)
• Optional domain-favicon avatars with privacy-preserving proxy (#22)
• Nested folder names resolved correctly in Sieve filter generator (#62)
• Russian and Ukrainian locales (1210 keys each, 10 locales total)
• Contact list batched to respect server maxObjectsInGet (#45)
• Favicon unread badge with live mailbox count refresh
• Plain text and HTML email printing (single-page, light-mode output, fits A4)
• OIDC surfaces a clear HTTPS-required message on plain HTTP (#23)

Release 1.5.1 (2026-04-17)

• Attachments render for mail originating from providers that stamp a Content-ID on every part (#58)
• Email-to-self delivered instead of being dropped by the MTA's duplicate-message check (#60)

Release 1.5.2 (2026-05-14)

• Patch CVE-2026-44578 (Next.js WebSocket SSRF, CVSS 8.6) by upgrading to 16.2.6, plus eleven other May 2026 advisories
• Bulk delete honours the "delete to trash" setting instead of always hard-deleting
• Favicon unread badge clears on the zero transition instead of sticking until the next refresh

Release 1.5.3 (2026-07-05)

• Stability release: fifteen bug fixes, several long-standing (see CHANGELOG)
• Content Security Policy enforced (was report-only)
• Sieve filter generation hardened against script injection from rule fields
• Failed sends, shared-mailbox bulk actions and trash deletion report honestly instead of silently failing
• "Stop processing" honoured after Discard/Reject (#67, thanks @travier)
• dompurify 3.4.11 and Next.js 16.2.10 security updates

Release 1.7.3 (2026-09-20)

• Dependency maintenance: Next.js 16.3.5, DOMPurify 3.4.15, React 19.3, next-intl 4.14.5, tooling patches

Release 1.7.2 (2026-09-19)

• SSO sessions survive reloads: offline_access requested so external IdPs issue a refresh token (#104, thanks @rriaz6601)
• OAUTH_SCOPES override for providers that reject or extend the default scope list

Release 1.7.1 (2026-08-28)

• OIDC logout accepted by Keycloak: end-session redirect carries id_token_hint and client_id (#102)
• Favicon unread badge shows on Firefox and Chrome/Linux (#66, thanks @jabiinfante)
• Sub-addressing "Learn More" dead end removed from Settings > Identities (#76)

Release 1.7.0 (2026-08-28)

• "All Inboxes" unified view across every account the session exposes (#53, #73, mail part of #28)
• Search set to Everywhere covers all accounts instead of only the primary
• Reply and send as a shared account through its own identity, attachments preserved, with an explicit fallback to your own address
• Account chips on list rows and account context in the viewer for shared-account mail
• New-mail push polling covers every account
• Unified inbox settings: show/hide toggle and per-account include list
• Partial-failure notice with per-account retry when an account fails to load
• Actions in merged views always target the account of the message you acted on
• Toast notifications fixed: the spam Undo button and batch move feedback were invisible
• Next.js 16.3.3 and dompurify 3.4.14 security updates

Release 1.6.0 (2026-07-05)

• Global cross-folder search by default with folder/everywhere/Trash-Junk scope chips (#75)
• Large mailboxes no longer hide mail behind search: anchor-based pagination (#71)
• Server-side sort by date, sender, subject or size
• Polish added as the eleventh language (thanks @priard)
• Browser language respected on first visit (#70)
• Full keyboard navigation for menus and dialogs (#94)

Planned Features

The next release focuses on real-time and PWA work: a native push transport and an installable app.

Real-time and PWA (1.8.0)

• JMAP WebSocket push transport (RFC 8887), replacing polling fallback
• PWA manifest, service worker, maskable icons, installable app
• Web Push notifications with VAPID
• Browser badge API for installed-app unread count

Mobile polish and composer (later)

• Pull-to-refresh on mobile
• Configurable swipe actions (archive, delete, mark read)
• Haptic feedback on destructive actions and long-press
• Web Share target (receive URLs/text from OS share sheet)
• WYSIWYG composer with multipart text/plain + text/html sending

Advanced features

• Free/busy queries (Principal/getAvailability)
• Calendar sharing UI (JMAP Sharing RFC 9670)
• Shared calendars and address books for multi-account access (#28)
• Email encryption (PGP/GPG)

Performance optimizations

• Email content caching
• Bundle size optimization
• Service worker for offline support
• Lazy loading for attachments

Testing (remaining)

• E2E tests with real JMAP server
• Accessibility testing
• Performance testing

Deployment

• Production build optimizations
• Monitoring and logging

Security enhancements

• Rate limiting

Known issues

• Next.js workspace root warning (cosmetic)

Contributing

Want to help implement a feature? Check out our CONTRIBUTING.md guide!