Design an Email Service (Gmail)

1Requirements

2Back-of-envelope estimation

3API design

4High-level design

The ingestion edge is a fleet of SMTP servers behind DNS MX records. They terminate TLS, apply connection-level defenses (IP reputation, rate limits, greylisting), and validate envelopes (SPF check, recipient exists). Most spam dies here with a cheap rejection before the message body is even transferred. Accepted messages are written to a durable write-ahead queue (Kafka) before the 250 OK is sent: the SMTP acknowledgment is a durability promise.

From the queue, a processing pipeline runs stages in order: parse MIME, extract and detach attachments to blob storage (content-addressed by hash so a 10 MB attachment sent to 500 recipients is stored once), run the spam pipeline, then deliver. Delivery means writing message metadata to the mailbox database, the body to message storage, and emitting an index event for search.

Mailbox storage is split by access pattern. Metadata (headers, flags, labels, thread ids) lives in a wide-row store like Bigtable or Cassandra keyed by (user id, message id) so an inbox page is one contiguous range read. Bodies live in blob storage, compressed, with hot recent messages cached. Threading is computed at delivery time using the References and In-Reply-To headers plus normalized subject fallback.

Search uses per-user index partitions in a Lucene-style engine (Elasticsearch or self-managed). Sharding by user keeps every query single-shard and makes tenant isolation structural. The indexer consumes delivery events from the queue, so a message is searchable within seconds. Attachment text extraction (PDF, docx) runs as a lower-priority enrichment that updates the index document.

Outbound mail is the mirror image: a submission service signs with DKIM, queues per destination domain, and retries with exponential backoff per SMTP rules (transient 4xx vs permanent 5xx). Sending reputation (IP warming, feedback loops, bounce handling) is its own operational discipline that determines whether your mail lands in other providers' inboxes.

5Data model

6Deep dives

7Rapid implementation: build the MVP

Theory is table stakes. Here is how you would stand up a working version fast, on a budget, with the core algorithm in real code.

1. 01Rent a cheap VPS with port 25 open (most clouds block it; Hetzner/OVH allow), set MX, SPF, DKIM, and DMARC DNS records for a test domain.
2. 02Stand up an SMTP listener with the smtp-server package: validate RCPT TO against a users table, stream DATA to disk, respond 250 only after fsync.
3. 03Parse stored raw mail with mailparser: extract headers, text/html bodies, and attachments; upload attachments to R2 keyed by sha256.
4. 04Pipe each message through Rspamd over its HTTP API; store the score and route to INBOX or SPAM label accordingly.
5. 05Create messages table with a generated tsvector column over subject and body, plus a GIN index; write the delivery insert.
6. 06Build a minimal web UI (Next.js): thread list grouped by normalized subject + References header, message view with sanitized HTML (DOMPurify), search box hitting the tsvector query.
7. 07Implement outbound send via nodemailer with DKIM signing, and a spam/not-spam button that relabels and logs the correction.
8. 08Test end-to-end: send from a Gmail account, verify delivery, search, attachment download via signed URL, and reply back to Gmail.

import { SMTPServer } from "smtp-server";
import { simpleParser } from "mailparser";
import { deliver } from "./pipeline";

const server = new SMTPServer({
  secure: false, // STARTTLS configured via key/cert opts in prod
  onRcptTo(addr, session, cb) {
    // Reject unknown recipients BEFORE the body is transferred.
    userExists(addr.address).then((ok) =>
      ok ? cb() : cb(Object.assign(new Error("5.1.1 No such user"), { responseCode: 550 }))
    );
  },
  onData(stream, session, cb) {
    simpleParser(stream)
      .then((mail) => deliver(session.envelope, mail)) // persist + fsync/replicate
      .then(() => cb(null)) // 250 OK: we now own the message
      .catch(() => {
        // Temp-fail: the remote MTA will retry. Never lose silently.
        const err = Object.assign(new Error("4.3.0 Try again later"), { responseCode: 451 });
        cb(err);
      });
  },
});
server.listen(25);

CREATE TABLE messages (
  user_id      BIGINT NOT NULL,
  message_id   UUID DEFAULT gen_random_uuid(),
  thread_key   TEXT NOT NULL,        -- normalized subject or References root
  from_addr    TEXT NOT NULL,
  subject      TEXT NOT NULL DEFAULT '',
  body_text    TEXT NOT NULL DEFAULT '',
  labels       TEXT[] NOT NULL DEFAULT ARRAY['INBOX'],
  spam_score   REAL NOT NULL DEFAULT 0,
  received_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
  search_vec   TSVECTOR GENERATED ALWAYS AS (
    setweight(to_tsvector('english', coalesce(subject, '')), 'A') ||
    setweight(to_tsvector('english', coalesce(body_text, '')), 'B')
  ) STORED,
  PRIMARY KEY (user_id, message_id)
);

CREATE INDEX idx_inbox ON messages (user_id, received_at DESC);
CREATE INDEX idx_search ON messages USING GIN (search_vec);

-- Search query with ranking blended toward recency:
SELECT message_id, subject,
       ts_rank(search_vec, q) * exp(-extract(epoch from now() - received_at) / 8.64e6) AS score
FROM messages, websearch_to_tsquery('english', 'invoice from alice') q
WHERE user_id = 42 AND search_vec @@ q
ORDER BY score DESC LIMIT 20;

import { createHash } from "crypto";
import { S3Client, PutObjectCommand, HeadObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({ endpoint: process.env.R2_ENDPOINT, region: "auto" });
const BUCKET = "mail-attachments";

export async function storeAttachment(content: Buffer, contentType: string) {
  const hash = createHash("sha256").update(content).digest("hex");
  const key = hash.slice(0, 2) + "/" + hash; // prefix for key distribution
  try {
    await s3.send(new HeadObjectCommand({ Bucket: BUCKET, Key: key }));
    return { key, deduped: true }; // identical bytes already stored
  } catch {
    await s3.send(new PutObjectCommand({
      Bucket: BUCKET,
      Key: key,
      Body: content,
      ContentType: contentType,
    }));
    return { key, deduped: false };
  }
}