Design Gmail

Assume 1.2 billion mailboxes with 500 million people active on a given day, 3 billion inbound SMTP attempts a day of which most are junk, and an average mailbox of 9 GB including attachments.

There are three faces to this system: SMTP for other mail servers, a JSON API for our own apps, and IMAP for third-party clients. The first two get most of the design attention.

Mail enters through a fleet of SMTP servers that face the open internet. They are designed to be suspicious and cheap: most of the work they do is saying no. Messages that survive the checks are written to a durable inbound queue replicated across zones before the server answers 250, so a crash after that point cannot lose the message.

Delivery workers drain the queue. For each recipient they run the user's filters, choose labels and a tab, find or create the conversation, store the body, and append a row to the user's mailbox. Each change also bumps the user's history id and emits an event that the indexer and the push notification service consume. The Mail API serves clients from the mailbox store and search index, and hands outgoing mail to an outbound queue that a separate SMTP fleet delivers with retries.

Most inbound connections are abusive, so the edge works in order of cost. First the IP: a reputation lookup against our own history and shared blocklists can refuse a connection or answer with a temporary 421, which legitimate servers retry and many spam tools do not. Next the envelope: RCPT TO for an unknown address is rejected immediately, which stops directory harvesting. Then the domain: SPF says whether this IP may send for the envelope domain, DKIM proves the domain signed the content, and DMARC tells us what the domain owner wants done when those fail.

Only after all that does the edge spend real CPU on content. A fast classifier looks at headers, URLs, text and sender history and returns a verdict in milliseconds: reject, quarantine, deliver to spam, or deliver. Rejecting during the SMTP session matters. If we accepted and later bounced, our bounce would go to a forged sender address and we would become a source of junk ourselves.

SMTP has a clear contract: before 250, the sender keeps the message and will retry; after 250, it is ours. So the edge writes the full message to a queue that is synchronously replicated to a second zone before replying. Everything downstream, from filters to indexing, can then fail and retry without risk, because the source of truth is already safe. If the queue write fails, the edge answers 451 and the sending server simply tries again later.

Folders put each message in exactly one place. Labels let a message be in Inbox, Work and Travel at once, and "archive" simply removes the Inbox label. Store the message row once, with its label set as a field, and maintain a secondary row per label: (user, label, reverse_time, message_id). Listing Inbox newest-first is then a short range scan of the Inbox rows for that user. Changing a label rewrites a handful of small rows rather than moving any data, which is why archiving thousands of messages is cheap.

Unread counts per label are kept as counters next to the label rows and corrected periodically by a recount, because counters that drift by one or two are a common source of user complaints.

The standard way to link replies is the Message-ID of each message plus the In-Reply-To and References headers of replies. When those are present, the delivery worker looks up the referenced ids in a small per-user map and attaches the new message to the same thread. Plenty of clients and mailing list servers mangle those headers, so fall back to a normalised subject (strip "Re:", "Fwd:" and list tags) within a time window and among overlapping participants. Keep the fallback conservative. Merging two unrelated "Invoice" emails into one thread is more annoying than leaving a reply on its own.

A single global index over trillions of messages would be enormous and would need a security filter on every query. Mail search is always scoped to one user, so build one small index per mailbox, stored as immutable segments in the same shard as the mailbox. New mail is added to a small in-memory segment and flushed periodically; background merges combine small segments into large ones, the way an LSM tree compacts. Structured operators such as from:, label: and after: become filters on indexed fields, and free text runs against the tokenised subject, body and attachment text.

Most users rarely search, so their segments live on cold storage and are loaded on first query, which costs a second or so once and is then cached. Heavy searchers keep theirs warm. Because the index is derived data, a corrupted or outdated one can always be rebuilt from the mailbox store.

Every mutation to a mailbox (new message, label change, deletion) appends an entry to that user's history log and increments its history id. A client keeps the last id it saw and asks for changes since then, receiving a short list instead of the whole inbox. Push notifications only need to say "something changed, fetch history", which keeps them tiny and safe to drop. The log is trimmed after a few weeks; a client that has been offline longer gets a 410 and does a full resync of recent mail.