Email Inbox Synchronization Service · Approach · designlab

Email Inbox Synchronization Service · Approach · designlab

Analysis

Reason about the problem

Approach

Turn it into a plan

Solution

The complete design

01 · Develop the design

Plan the design

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.

Stage 1

Separate content and mailbox state

Put immutable bodies in Object storage and mutable metadata in the Mailbox store. The API service reauthorizes each body read; knowing a digest is not permission.

Stage 2

Journal old-message changes

Spam workers commit metadata, deduplication outcomes and a mailbox change sequence in the Mailbox store transaction. Flags and deletions need entries even when a message is old.

Stage 3

Pin the resync boundary

The API service pins a Mailbox store watermark for a snapshot. Retain newer changes until the client finishes its bounded resync lease; update the Search index asynchronously.

02 · Work through the method

Step-by-step approach

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 · Justify the choices

Why this approach works

What should a device cursor represent?

A committed mailbox change sequence

Flags and deletions can change old messages, so timestamp-based paging is not a complete change cursor.

Can a message header alone always identify a unique delivery?

No; use the authenticated provider delivery identity under a declared dedup scope

Headers may be absent, duplicated or attacker-controlled and are not a universal exactly-once key.

What if a device cursor predates retained changes?

Return resetRequired with a consistent snapshot path

An expired change history cannot be reconstructed by silently returning an empty page.

04 · Plan the evidence

Validation strategy

Duplicate ingress deliveries create one mailbox message under the provider contract.
Changing an old message flag appears in the next delta page.
An expired cursor triggers snapshot recovery without missing concurrent changes.
A body digest or another mailbox’s cursor cannot bypass authorization.

Trade-offs to explain

Per-mailbox ordering simplifies sync but a very hot shared mailbox can become a bottleneck.
Retained tombstones and snapshot leases consume storage while protecting offline-device recovery.
Immutable bodies enable deduplication but require independent access control and safe orphan collection.

Read the detailed solution Build my design