Email Inbox Synchronization Service · Analysis · designlab

Email Inbox Synchronization Service · Analysis · designlab

Analysis

Reason about the problem

Approach

Turn it into a plan

Solution

The complete design

01 · Frame the problem

Understand the central challenge

Build an inbox with an API service for reads and ingestion, a queue and spam workers for delivery, a mailbox store for metadata and ordered changes, and object storage for immutable bodies. Clients synchronize through retained mailbox sequences; outbound delivery and mail protocol implementation are separate.

Mailbox metadata needs ordered synchronization while message bodies remain immutable and separately authorized. Analyse cursor retention, snapshot boundaries and concurrent flag/folder changes before designing client sync.

02 · Find the design pressure

Start simple, then identify the gap

Begin with one mailbox-local Mailbox store owner and transactional Mailbox store change sequence. Polling mutable pages misses intervening moves or deletions. Use snapshot-plus-watermark recovery and provider-independent revision checks to preserve a coherent client mirror.

Route Client requests through the Load balancer to the API service. Queue inbound deliveries for Spam workers, store immutable bodies in Object storage, and serialize metadata and change sequences in the Mailbox store. Cache reads and update the Search index asynchronously; clients use snapshot-plus-cursor recovery when retained changes expire. The API service validates authenticated ingress identity and bounded message metadata, then appends to the Queue. Spam workers scan the message, stage verified bytes in Object storage and transactionally insert Mailbox store metadata, the deduplication outcome and a change sequence. Clean orphan bodies separately. Client reads pass through the Load balancer and API service. Cache hot mailbox metadata and invalidate it after mutations. Authorize each Object storage fetch independently of its content identity. Flag and folder mutations require the expected message revision. Commit idempotency results and change entries in the same Mailbox store transaction; retain deletion tombstones until dependent sync horizons expire. Feed committed Mailbox store changes to the Search index off the request path. Versioned, idempotent indexing tolerates retries and an unavailable index without blocking message acceptance. The API service pages committed mailbox changes by sequence. For expired cursors, return resetRequired and a pinned snapshot with a watermark and lease. Clients install it, then replay newer revisions before releasing the lease.

03 · Define success

Requirements to preserve

Deduplicate ingress under a provider-scoped delivery identity.
Commit mailbox metadata and change entries atomically.
Support revision-checked flag updates and deletion tombstones.
Recover devices whose change cursor is older than retained history.

Workload: 30,000 reads/s, 8,000 writes/s, 3000 B records, 250 ms read p99 target. These are exercise assumptions; the Solution includes capacity formulas.

04 · Identify the correctness boundary

Consistency, ownership and failure boundaries

Mutable flags, folders and deletions share mailbox-local ordering, while immutable message bodies are separately authorized. Commit a metadata change and its journal entry together. Snapshot-plus-watermark recovery closes the gap when an incremental cursor is older than retained history.

05 · Make it concrete

Reason through a worked example

A client reads snapshot watermark 500, then consumes changes after 500 while receiving remaining snapshot pages. A concurrent move to another folder appears in the journal and is not lost. Replaying that move is revision-safe, and a deleted message's body cannot be fetched through an unscoped object reference.

Continue to the approach Try my own design