Design an Email Client (Gmail style)

A frontend system design walkthrough for a web mail client. The focus is a local-first cache, incremental sync, an offline send queue, and safe rendering of HTML that strangers wrote.

Frontend system design · Design problem

Design a mail client that opens the inbox from local data in under a second. It stays correct across tabs and devices, keeps working offline, and never lets an email run code in the app.

Correctness contract: A message the user sends is never lost and never sent twice. The local view always converges to the server state after sync. No email body can run script, read app data, or submit forms in the app's origin.

You know HTML, JavaScript, HTTP, and basic React. IndexedDB, Service Workers, and iframe sandboxing are explained below. Numbers are teaching estimates, not measurements of any real product.

An email client looks like a list and a reading pane. The hard parts are hidden. A heavy user has 100,000 messages, but the screen shows 15 rows. People open the app many times a day and expect it to be instant, even on a train with no signal. They act on mail from a phone and a laptop at once, so two devices change the same thread. And every message body is HTML written by someone you do not trust, including attackers. This guide shows how a local-first design handles all of this. The client keeps a copy of recent mail in IndexedDB, shows it at once, and syncs changes in the background with a history cursor.

Contents

  1. Concepts to understand first
  2. 1. Clarifying questions and requirements
  3. 2. Scope and budgets
  4. 3. High-level architecture
  5. 4. Data model
  6. 5. Interface and API
  7. 6. Deep dive: the virtualized thread list
  8. 7. Deep dive: local-first cache and history sync
  9. 8. Deep dive: offline compose and the send queue
  10. 9. Deep dive: rendering HTML email safely
  11. 10. Deep dive: search, local and server
  12. 11. Deep dive: labels, shortcuts, attachments, accounts
  13. 12. Failure modes
  14. 13. Trade-offs
  15. 14. 45-minute interview walkthrough
  16. 15. Summary
  17. 16. Common mistakes
  18. Worked example: send on a train, then sync
  19. Code lab: history sync with pending edits
  20. Check yourself
  21. Key terms
  22. Further reading

Concepts to understand first

Local-first cache

The UI reads from a local database first and shows that data at once. The network only updates the local data. The UI never waits on the network to show something it already has.

Example. The user opens the app. The inbox renders from IndexedDB in 300 ms. A sync request then brings 4 new messages, which slide in at the top.

Limit. Local data can be stale. Show a quiet "updating" state, and never show stale data as final for actions that matter, such as "message sent".

History id (sync cursor)

The server gives every mailbox change an increasing number. The client stores the last number it applied. Next time it asks "what changed after number N?" and gets only the changes.

Example. The client stored historyId 5120. It calls GET /history?startHistoryId=5120 and gets records 5121 to 5130: two new messages, one label change, one delete.

Limit. The server keeps history only for a while, such as one week. If the cursor is too old, the server says so and the client must do a full resync.

Outbox with idempotency keys

Every user action that changes the server is first written to a durable local queue. Each entry has a unique key. The server remembers keys it has seen, so a retry with the same key does nothing new.

Example. Send times out after the server got it. The client retries with the same Idempotency-Key: op-7f3. The server returns the first result and does not send a second copy.

Limit. The server must store keys long enough to cover all retries, such as 24 hours. Keys must be made on the client before the first attempt.

Sandboxed iframe

An <iframe sandbox> turns off scripts, forms, popups, and more inside the frame. You turn features back on one by one. Styles inside the frame cannot leak out to the app.

Example. An email has <style>body{display:none}</style>. In a sandboxed frame it hides only its own body, not the app.

Limit. Never set both allow-scripts and allow-same-origin. Together they let the frame remove its own sandbox.

List virtualization

Only the rows near the viewport exist in the DOM. Spacers above and below keep the scrollbar the right size. Rows are created and reused as the user scrolls.

Example. A label with 20,000 threads renders about 35 rows at a time, not 20,000. The DOM stays under 1,500 nodes.

Limit. Browser find (Ctrl+F) cannot see rows that are not rendered. Screen readers need aria-setsize and aria-posinset to know the real size.

1. Clarifying questions and requirements

Ask questions that change the design:

Functional requirements

Non-functional requirements

2. Scope and budgets

Data size

Storage quota

Browsers give an origin a share of free disk, often many gigabytes on desktop and less on phones. Read the real numbers with navigator.storage.estimate(). Ask for navigator.storage.persist() so the browser does not evict the mail cache under pressure. Keep a self-imposed cap, such as 500 MB, and evict old bodies first. Metadata is small, so keep it longer.

DOM and frame budget

Bundle budget

Tip

Cache the app shell in a Service Worker with precaching. A warm start then needs zero network for code. Combined with IndexedDB data, the inbox renders while the network is still waking up.

3. High-level architecture

Architecture diagram: ThreadList, ThreadView, and Compose read and write an in-memory store. The store loads from IndexedDB and queues actions to a sync engine in a worker. The sync engine talks to the mail API and a push channel. Message bodies render in a sandboxed iframe that loads images through an image proxy.
Figure 1. The UI talks only to the in-memory store. The sync engine is the only part that talks to the server. Email HTML lives in its own sandboxed frame.

Layers

Many tabs, one sync engine

Users open mail in several tabs. If each tab ran its own sync, they would fetch the same history three times and race on writes. Use the Web Locks API to elect a leader. Each tab calls navigator.locks.request("sync-acct-1", ...). Only one holds the lock and runs sync. When that tab closes, the lock passes to another tab automatically. The leader posts changes on a BroadcastChannel, and other tabs refresh their store from IndexedDB. A SharedWorker is another option, but it is not supported in every mobile browser.

Intuition

The local database is the source of truth for the UI. The server is the source of truth for the database. The UI never asks the server directly. This one rule removes most loading spinners and most race conditions.

4. Data model

// IndexedDB database "mail-<accountId>", version 3
// Object stores and their indexes:
threads:   { id, historyId, subject, snippet, participants: string[],
             labelIds: string[], lastMessageAt: number, unreadCount: number,
             messageIds: string[], hasAttachments: boolean }
messages:  { id, threadId, from, to: string[], cc: string[], date: number,
             labelIds: string[], snippet: string, bodyState: "none" | "cached",
             sanitizedHtml?: string, attachments: { id, name, size, mime }[] }
threadLabels: { key: [labelId, lastMessageAt, threadId] }   // one row per (label, thread)
labels:    { id, name, color, type: "system" | "user", unread: number, total: number }
outbox:    { opId, seq, kind: "send" | "modify" | "draft", payload, attempts: number,
             nextAttemptAt: number, createdAt: number }
syncState: { key: "cursor", historyId: number, fullSyncDoneAt: number }
search:    { token, messageIds: string[] }            // small local inverted index

// In-memory store
type Store = {
  threads: Record<string, Thread>;
  messages: Record<string, Message>;
  labels: Record<string, Label>;
  lists: Record<string, { ids: string[]; complete: boolean; nextPageToken?: string }>;  // key: label or query
  pending: { opId: string; threadIds: string[]; addLabels: string[]; removeLabels: string[] }[];
  selection: Set<string>;
  focusedThreadId: string | null;
};

5. Interface and API

Server API

Real-time channel

A WebSocket or EventSource carries only small pings: { "historyId": 5131 }. The client does not trust the ping for data. It just calls the history endpoint. This keeps one code path for changes, whether they came from a ping, a focus event, or a timer. If the push channel drops, poll history every 60 seconds and on visibilitychange to visible.

Component props

<ThreadList listKey="label:INBOX" rowHeight={56} overscan={10}
            onOpen={(threadId) => ...} onSelect={(ids) => ...} />
<ThreadView threadId="t_8812" onAction={(action, ids) => ...} />
<MessageBody html={sanitizedHtml} showRemoteImages={false} onHeight={(px) => ...} />
<Compose draftId="d_19" mode="reply" inReplyTo="m_771" />

6. Deep dive: the virtualized thread list

Fixed row height

Mail rows have a fixed height per density setting. This is a big gift. The visible range is simple math: first = floor(scrollTop / rowHeight) and count = ceil(viewportHeight / rowHeight). No measuring is needed. The scroll container gets a spacer of total * rowHeight pixels, and rows are absolutely positioned with transform: translateY(index * rowHeight).

Reading scroll without jank

Paging and unknown totals

The label count tells us the total, such as 20,000. The client may have only the first 500 ids. Rows past the loaded range render as grey skeletons. An IntersectionObserver on a sentinel near the end of loaded rows triggers the next page from IndexedDB first, then the server.

Stable scroll when new mail arrives

New mail is inserted at the top. If the user is scrolled down, inserting rows above pushes everything down and the row under the cursor jumps. Two fixes:

Selection and bulk actions

Selection is a set of thread ids, not DOM checkboxes. Shift+click selects a range by index. "Select all 20,000" is a flag plus the list key, not 20,000 ids. The server applies it as a query-based batch job.

Accessibility

Mistake

Letting the focused row be recycled. When the user scrolls with the wheel, the focused row leaves the window, React removes it, and focus jumps to body. Always keep the focused row mounted.

7. Deep dive: local-first cache and history sync

Sequence diagram: the user sends offline, the store inserts optimistically, the op is persisted to the IndexedDB outbox, when the network returns the sync engine sends with an idempotency key, then pulls history since the cursor, applies records, drops the op, and notifies other tabs.
Figure 2. The outbox write happens before the UI says "queued". The pending op is dropped only after the server's version is applied.

First sync

  1. Fetch the first 50 threads of the inbox and render them. Save the response's historyId as the cursor right away, before any more paging.
  2. In the background, page through more threads for the inbox and other labels. Store each page in one IndexedDB transaction.
  3. Any change that happens during this backfill shows up in history after the cursor, so nothing is missed.

The order matters. Saving the cursor first means "everything after this point will come through history". If you saved the cursor at the end of a long backfill, changes made during the backfill could be lost.

Incremental sync

  1. A trigger fires: a push ping, the tab becoming visible, the online event, or a 60 second timer.
  2. The leader tab calls GET /history?startHistoryId=cursor and pages until done.
  3. It applies records in order in one IndexedDB transaction: add messages, delete messages, add and remove labels.
  4. In the same transaction, it advances the cursor to the last applied record. Data and cursor commit together or not at all.
  5. It broadcasts "changed thread ids" to all tabs, which re-read those threads.

Why apply must be idempotent

A crash can happen after the server responded but before the transaction committed. Next time, the client asks again from the old cursor and receives the same records. Applying "add label X" twice must give the same result as once. Using sets for labels and ids for messages makes every record idempotent. Skip any record with an id at or below the cursor.

Optimistic edits and rebasing

When the user archives a thread, the change must show in under 100 ms. The client records a pending op and the view applies it on top of server data. Then sync runs:

Expired cursor

After a week offline, the server returns historyExpired. Do a full resync of metadata for recent threads. Keep cached bodies whose message ids still exist, because bodies never change. Keep the outbox. It is replayed after the resync, and idempotency keys make that safe.

Interview

Interviewers often ask "what if the user changes something on two devices?". Answer with the model: server order wins for server state, and local pending ops are re-applied on top until confirmed. Label changes commute, so there are few real conflicts. The hard case is drafts, covered next.

8. Deep dive: offline compose and the send queue

Drafts

Send

  1. The user clicks Send. The client creates opId, a random id from crypto.randomUUID().
  2. It writes the outbox entry to IndexedDB and waits for the transaction to complete. Only then does the UI say "Sending" or "Queued".
  3. The message appears in Sent with a clock icon, and the compose window closes.
  4. "Undo send" holds the request for a short delay, such as 5 to 30 seconds. Undo deletes the outbox entry and reopens the draft. The delay lives in the outbox entry as nextAttemptAt, so it also survives a reload.
  5. When the delay ends and the network is up, the sync engine posts the message with the Idempotency-Key header.
  6. On success, the server returns the real message id. The client maps the temporary id to the real id in one transaction.

Retries

When the tab is closed

The Background Sync API lets the Service Worker run the outbox after connectivity returns, even if the tab is closed. Register with registration.sync.register("outbox"). It is supported in Chromium-based browsers only. Elsewhere, the outbox runs the next time any tab opens. The UI should say "will send when you are back online" so the user is not surprised.

Mistake

Showing "Sent" when the request starts. If the tab closes before the response, the user believes the mail left. The honest states are Queued, Sending, Sent, and Failed. Only a server response moves a message to Sent.

9. Deep dive: rendering HTML email safely

An email body is untrusted HTML. It can contain scripts, event handlers, forms that phish for passwords, CSS that covers the whole app, and tracking pixels. Defense comes in layers. If one layer fails, the next one still holds.

Layer 1: sanitize with an allowlist

Layer 2: a sandboxed frame

Render the sanitized HTML in <iframe sandbox="allow-same-origin allow-popups allow-popups-to-escape-sandbox" srcdoc="...">.

Layer 3: Content Security Policy

Put a strict CSP inside the srcdoc with a meta tag: script-src 'none', img-src limited to the image proxy and data:. The app itself also uses a strict CSP with nonces and Trusted Types. Then a bug that writes email HTML into the main DOM fails loudly.

Remote images and tracking

A 1 by 1 pixel image tells the sender when you opened the mail and from which IP. Rewrite every remote image URL to the image proxy, for example /proxy?url=...&sig=.... The proxy fetches the image from its own servers, so the sender sees the proxy's IP. It can also cache the image, which defeats per-open timing. For unknown senders, block images until the user clicks "show images".

Sizing and performance

Dark mode

Many emails hard-code black text on white. Forcing dark colors breaks their design. A safe default is to render the email on a light card even in dark mode. Offer an optional color inversion with a CSS filter as a user setting.

Tip

Test the sanitizer with a corpus of known attack strings, such as SVG with onload, nested <noscript> tricks, and mixed-case JaVaScRiPt: URLs. Run it in CI on every sanitizer upgrade.

Two engines

Local index

Tokenize subject, sender, and snippet into lowercase words. Store an inverted index in IndexedDB: each token maps to a list of message ids. Add prefix entries for the first 3 to 5 letters, so "inv" finds "invoice". Update the index in the same sync transaction that adds messages. For 5,000 threads the index is a few megabytes.

Merging results

  1. As the user types, debounce 150 ms and show local suggestions: contacts, labels, and top matching threads.
  2. On Enter, show local results at once with a note: "Showing results from this device."
  3. Send the server query in parallel with an AbortController. Cancel it if the query changes.
  4. When server results arrive, merge by message id and keep the server order. Do not reorder rows the user is looking at. Append new ones or replace in one swap.

Operators

Parse operators on the client into a small query object: { from: "ana", hasAttachment: true, label: "work", text: "invoice" }. Local search can evaluate it directly. Server search receives the raw string so both sides agree on syntax.

11. Deep dive: labels, shortcuts, attachments, accounts

Labels

Labels are many-to-many tags, not folders. "Archive" means remove the INBOX label. Unread counts per label live on the label record. Update them optimistically with pending ops, then correct them from the server, which owns the true count. The label nav shows counts only for labels the user chooses, because computing all counts is costly.

Keyboard shortcuts

Attachments

Multiple accounts

12. Failure modes

13. Trade-offs

Local-first vs network-first

Ping plus history vs full data push

Sandboxed iframe vs Shadow DOM

How much to cache

14. 45-minute interview walkthrough

  1. Minutes 0 to 5: clarify. Offline scope, accounts, compose features, API shape. List functional and non-functional requirements.
  2. Minutes 5 to 9: budgets. 100,000 messages, 1 KB metadata, 30 KB bodies, cache plan, 40 rendered rows, 150 KB critical bundle.
  3. Minutes 9 to 16: architecture. UI, store, sync engine in a worker, IndexedDB per account, Web Locks leader, push ping.
  4. Minutes 16 to 21: data model and API. Normalized stores, label index, outbox, cursor. History endpoint and idempotency keys.
  5. Minutes 21 to 29: sync. First sync with cursor saved first, incremental sync in one transaction, optimistic ops, rebasing, expired cursor.
  6. Minutes 29 to 35: safety. Sanitizer allowlist, sandbox attributes, CSP, image proxy, attachment origin.
  7. Minutes 35 to 40: one more dive. Virtualized list with stable scroll, or offline send with undo, or search merging.
  8. Minutes 40 to 45: failures, trade-offs, metrics. Measure warm start time, sync lag, outbox age, and send failure rate.

15. Summary

16. Common mistakes

Worked example: send on a train, then sync

Ana has two tabs open on her laptop. Her phone is also signed in. The cursor is historyId 5120. Her train enters a tunnel.

  1. The offline event fires. The app shows a small "Offline" banner. Tab A holds the Web Lock and is the sync leader.
  2. Ana archives 3 threads with e. Each creates a pending op in the store and an outbox entry. The rows disappear from the inbox in one frame.
  3. She replies to Ben. Drafts autosave to IndexedDB every 500 ms. She clicks Send.
  4. The client creates opId op-7f3 and writes the outbox entry with nextAttemptAt = now + 10 s for undo send. After the transaction completes, the message shows in Sent with a clock icon.
  5. Meanwhile on her phone, which has signal, she stars one of the threads she just archived. The server records this as 5121.
  6. The train leaves the tunnel. The online event fires in Tab A. The sync engine reads the outbox in seq order.
  7. It posts the 3 modify ops and the send, each with its idempotency key. The send's first attempt times out after the server accepted it.
  8. The engine retries the send after 2 seconds with the same key op-7f3. The server returns the stored result: message id m_9001. Ben gets one copy.
  9. The engine calls GET /history?startHistoryId=5120. It gets 5121 (star from the phone), 5122 to 5124 (her archives), 5125 (her sent message), and 5126 (a new mail from Chen).
  10. In one IndexedDB transaction, it applies all records, maps the temp id to m_9001, deletes the 4 outbox entries, and sets the cursor to 5126.
  11. It drops the pending ops from the store and broadcasts the changed thread ids. Tab B re-reads them. Both tabs show the star, the archives, the sent reply, and Chen's new mail.
  12. Chen's message has a tracking pixel. The sanitizer rewrote it to the image proxy, and the frame blocks it until Ana clicks "show images".

Code lab: history sync with pending edits

This script models the core sync loop. It applies history records idempotently, keeps optimistic edits separate, and shows the view as server data plus pending ops. Save it as sync.mjs and run node sync.mjs with Node 18 or later.

function createStore() { return { historyId: 0, msgs: new Map(), pending: [] }; }

function applyHistory(store, resp) {
  if (resp.expired) return "FULL_RESYNC"; // server no longer keeps history this old
  for (const h of resp.history) {
    if (h.id <= store.historyId) continue; // replayed record: skip, so it stays idempotent
    for (const m of h.added ?? []) store.msgs.set(m.id, { ...m, labels: new Set(m.labels) });
    for (const id of h.deleted ?? []) store.msgs.delete(id);
    for (const c of h.labelChanges ?? []) {
      const m = store.msgs.get(c.id);
      if (!m) continue;
      c.add?.forEach((l) => m.labels.add(l));
      c.remove?.forEach((l) => m.labels.delete(l));
    }
    store.historyId = h.id;
  }
  return "OK";
}

function view(store) { // server truth, then local pending edits on top
  const out = new Map();
  for (const [id, m] of store.msgs) out.set(id, { ...m, labels: new Set(m.labels) });
  for (const op of store.pending) {
    const m = out.get(op.id);
    if (!m) continue;
    op.add?.forEach((l) => m.labels.add(l));
    op.remove?.forEach((l) => m.labels.delete(l));
  }
  return out;
}

const show = (st) => [...view(st).values()].map((m) => `${m.id}:${[...m.labels].join("+")}`).join("  ");
const s = createStore();
applyHistory(s, { history: [{ id: 1, added: [
  { id: "m1", subject: "Lunch?", labels: ["INBOX", "UNREAD"] },
  { id: "m2", subject: "Invoice", labels: ["INBOX"] }] }] });
console.log("start:     ", show(s));

s.pending.push({ opId: "op-1", id: "m1", remove: ["INBOX"] }); // archive while offline
console.log("optimistic:", show(s));

// Another device marked m1 read. The page also replays old record 1.
applyHistory(s, { history: [{ id: 1, added: [] }, { id: 2, labelChanges: [{ id: "m1", remove: ["UNREAD"] }] }] });
console.log("synced:    ", show(s));

// Back online: server applies op-1 and reports it as record 3. Apply first, then drop the op.
applyHistory(s, { history: [{ id: 3, labelChanges: [{ id: "m1", remove: ["INBOX"] }] }] });
s.pending = s.pending.filter((op) => op.opId !== "op-1");
console.log("acked:     ", show(s), " historyId", s.historyId);
console.log("old cursor:", applyHistory(s, { expired: true }));

Expected output: first m1:INBOX+UNREAD, then m1:UNREAD (archived locally). Next comes m1: with no labels, because it is archived locally and read on the other device. The ack line is the same, with historyId 3. The last line is FULL_RESYNC. Try swapping the last two steps, so the op is dropped before record 3 is applied. Print the view between them and you will see m1 briefly back in the inbox. That is the flicker the design avoids.

Check yourself

  1. Why must the client save the history cursor before it starts the long backfill of old threads?
    Answer

    Changes that happen during the backfill get history ids after the saved cursor, so the next incremental sync picks them up. If the cursor were saved at the end, changes made during the backfill could fall before it and be lost.

  2. A send request times out. Is it safe to retry? What makes it safe?
    Answer

    Yes, if the retry carries the same idempotency key made before the first attempt. The server stores the key with the result and returns that result for a repeat, without sending a second email.

  3. Why is sandbox="allow-scripts allow-same-origin" dangerous for email bodies?
    Answer

    With both, a script in the frame runs with the parent's origin. It can reach into the parent, or remove the sandbox attribute from its own frame and reload. The sandbox then gives no protection.

  4. The user archives a thread offline. Another device marks it read. What does the user see after sync, before the archive is confirmed?
    Answer

    The view is new server data plus pending ops. The thread stays out of the inbox because the pending archive is applied on top. It shows as read because the server data now says so.

  5. Why use Web Locks in a multi-tab mail client?
    Answer

    To make sure only one tab per account runs sync and the outbox. Without it, tabs fetch the same history several times and race on IndexedDB writes. The lock moves to another tab when the leader closes.

  6. Why serve attachments from a different origin than the app?
    Answer

    An attached HTML or SVG file can contain script. Opened from the app's origin, that script could read cookies, storage, and mail. A separate origin with Content-Disposition: attachment keeps it away from app data.

Key terms

Local-first
A design where the UI reads from local storage first and the network only updates that storage.
History id
An increasing number for each mailbox change, used as a cursor for incremental sync.
Full resync
Re-downloading recent state when the cursor is too old for the server's history.
Outbox
A durable local queue of user actions waiting to reach the server.
Idempotency key
A unique id sent with a request so the server can ignore repeats.
Optimistic update
Showing the result of an action before the server confirms it.
Sanitizer
Code that removes dangerous tags, attributes, and URLs from HTML using an allowlist.
Sandboxed iframe
A frame with the sandbox attribute, which turns off scripts, forms, and other features by default.
srcdoc
An iframe attribute that holds the frame's HTML inline instead of loading a URL.
Image proxy
A server that fetches remote images for the user, hiding the user's IP and open time.
Web Locks API
A browser API that lets tabs of one origin share a named lock, used for leader election.
Background Sync
A Service Worker API that runs a task when connectivity returns, even with the tab closed.

Further reading

Primary references