diff --git a/README.md b/README.md
index 0ca6a2a..191b319 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ npx @smails/cli create      # create a mailbox (token saved to ~/.smails)
 npx @smails/cli inbox       # list messages
 npx @smails/cli read <id>   # read a message (id prefix is enough)
 npx @smails/cli whoami      # show the current address
-npx @smails/cli create --new  # replace with a fresh mailbox
+npx @smails/cli create --force  # replace with a fresh mailbox
 ```
 
 ### MCP (for AI agents)
diff --git a/cli/README.md b/cli/README.md
index 74f8fdb..bca5d85 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -14,7 +14,7 @@ npx @smails/cli inbox         # list messages
 npx @smails/cli read <id>     # read a message (full id or short prefix)
 npx @smails/cli delete <id>   # delete a message
 npx @smails/cli whoami        # show the current address
-npx @smails/cli create --new  # replace with a fresh mailbox
+npx @smails/cli create --force  # replace with a fresh mailbox
 ```
 
 Install globally for a shorter command:
diff --git a/cli/src/api.ts b/cli/src/api.ts
index 109f944..dcbbf28 100644
--- a/cli/src/api.ts
+++ b/cli/src/api.ts
@@ -23,29 +23,39 @@ export class SmailsAPI {
 
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 15000);
-    let res: Response;
     try {
-      res = await fetch(`${this.baseUrl}${path}`, {
+      const res = await fetch(`${this.baseUrl}${path}`, {
         ...options,
         headers,
         signal: controller.signal,
       });
+      // Read the body inside the try so the 15s deadline also covers a stalled
+      // response body, not just the headers.
+      if (!res.ok) {
+        const body = (await res.json().catch((e) => {
+          // Let an abort during the body read fall through to the timeout
+          // mapping below instead of being downgraded to the status text.
+          if (e instanceof Error && e.name === "AbortError") throw e;
+          return { error: res.statusText };
+        })) as {
+          error?: string;
+        };
+        throw new Error(body.error || `HTTP ${res.status}`);
+      }
+      return (await res.json()) as T;
     } catch (err) {
       if (err instanceof Error && err.name === "AbortError") {
         throw new Error(`Request timed out after 15s (${this.baseUrl})`);
       }
-      throw new Error(`Network error: cannot reach ${this.baseUrl}`);
+      // fetch() rejects with a TypeError on network failures (DNS, refused, …);
+      // our own HTTP errors above are plain Errors and re-throw unchanged.
+      if (err instanceof TypeError) {
+        throw new Error(`Network error: cannot reach ${this.baseUrl}`);
+      }
+      throw err;
     } finally {
       clearTimeout(timeout);
     }
-
-    if (!res.ok) {
-      const body = (await res.json().catch(() => ({ error: res.statusText }))) as {
-        error?: string;
-      };
-      throw new Error(body.error || `HTTP ${res.status}`);
-    }
-    return res.json() as Promise<T>;
   }
 
   async getDomains(): Promise<string[]> {
@@ -84,10 +94,10 @@ export class SmailsAPI {
     text: string | null;
     attachments: unknown[];
   }> {
-    return this.request(`/api/mailbox/messages/${id}`);
+    return this.request(`/api/mailbox/messages/${encodeURIComponent(id)}`);
   }
 
   async deleteMessage(id: string): Promise<void> {
-    await this.request(`/api/mailbox/messages/${id}`, { method: "DELETE" });
+    await this.request(`/api/mailbox/messages/${encodeURIComponent(id)}`, { method: "DELETE" });
   }
 }
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index c09e4d1..6e5be4a 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -1,5 +1,6 @@
 import { SmailsAPI } from "./api.js";
-import { loadConfig, saveConfig } from "./config.js";
+import { loadConfig } from "./config.js";
+import { createMailbox } from "./mailbox.js";
 
 const HELP = `smails — disposable email for humans and agents
 
@@ -7,7 +8,7 @@ Usage: smails <command> [options]
 
 Commands:
   create [--domain <d>]   Create a new mailbox (token saved to ~/.smails)
-  create --new            Replace the current mailbox with a fresh one
+  create --force          Replace the current mailbox with a fresh one
   inbox                   List messages
   read <id>               Read a message (full id or short prefix)
   delete <id>             Delete a message (full id or short prefix)
@@ -56,16 +57,12 @@ async function resolveMessageId(api: SmailsAPI, idOrPrefix: string): Promise<str
 }
 
 async function create(args: string[]) {
-  const existing = loadConfig();
-  const isNew = args.includes("--new");
-  if (existing && !isNew) {
-    console.log(`You already have a mailbox: ${existing.address}`);
-    console.log("Use `smails create --new` to create a new one.");
+  const result = await createMailbox(flag(args, "--domain"), args.includes("--force"));
+  if (!result.created) {
+    console.log(`You already have a mailbox: ${result.existing}`);
+    console.log("Use `smails create --force` to create a new one.");
     return;
   }
-  const api = new SmailsAPI();
-  const result = await api.createMailbox(flag(args, "--domain"));
-  saveConfig({ address: result.address, token: result.token });
   console.log(`Mailbox created: ${result.address}`);
 }
 
diff --git a/cli/src/config.ts b/cli/src/config.ts
index 096cfa2..53504dd 100644
--- a/cli/src/config.ts
+++ b/cli/src/config.ts
@@ -10,11 +10,21 @@ interface Config {
 }
 
 export function loadConfig(): Config | null {
+  let data: string;
+  try {
+    data = readFileSync(CONFIG_PATH, "utf-8");
+  } catch (err) {
+    // No mailbox yet — that's fine. Any other read error (permissions, etc.)
+    // must surface so we never treat an existing config as absent.
+    if ((err as { code?: string }).code === "ENOENT") return null;
+    throw new Error(`Cannot read ${CONFIG_PATH}: ${(err as Error).message}`);
+  }
   try {
-    const data = readFileSync(CONFIG_PATH, "utf-8");
     return JSON.parse(data) as Config;
   } catch {
-    return null;
+    throw new Error(
+      `Config file ${CONFIG_PATH} is corrupt. Remove it (or run \`smails create --force\`) to start over.`,
+    );
   }
 }
 
diff --git a/cli/src/mailbox.ts b/cli/src/mailbox.ts
new file mode 100644
index 0000000..87e8db8
--- /dev/null
+++ b/cli/src/mailbox.ts
@@ -0,0 +1,28 @@
+import { SmailsAPI } from "./api.js";
+import { loadConfig, saveConfig } from "./config.js";
+
+export type CreateResult =
+  | { created: true; address: string }
+  | { created: false; existing: string };
+
+/**
+ * Create a mailbox and persist it to the local config. Shared by the CLI
+ * `create` command and the MCP `create_mailbox` tool so the recovery semantics
+ * live in one place.
+ *
+ * When `force` is false an existing saved mailbox short-circuits with
+ * `created: false`. `force` also skips loadConfig entirely so it can recover even
+ * when the saved config is unreadable/corrupt (loadConfig throws in that case).
+ */
+export async function createMailbox(
+  domain: string | undefined,
+  force: boolean,
+): Promise<CreateResult> {
+  if (!force) {
+    const existing = loadConfig();
+    if (existing) return { created: false, existing: existing.address };
+  }
+  const result = await new SmailsAPI().createMailbox(domain);
+  saveConfig({ address: result.address, token: result.token });
+  return { created: true, address: result.address };
+}
diff --git a/cli/src/mcp.ts b/cli/src/mcp.ts
index e3fa593..24fb571 100644
--- a/cli/src/mcp.ts
+++ b/cli/src/mcp.ts
@@ -3,7 +3,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import pkg from "../package.json" with { type: "json" };
 import { SmailsAPI } from "./api.js";
-import { loadConfig, saveConfig } from "./config.js";
+import { loadConfig } from "./config.js";
+import { createMailbox } from "./mailbox.js";
 
 export async function runMCP() {
   const server = new McpServer({
@@ -27,20 +28,17 @@ export async function runMCP() {
       force: z.boolean().optional().describe("Set to true to replace an existing mailbox"),
     },
     async ({ domain, force }) => {
-      const existing = loadConfig();
-      if (existing && !force) {
+      const result = await createMailbox(domain, force ?? false);
+      if (!result.created) {
         return {
           content: [
             {
               type: "text",
-              text: `A mailbox already exists: ${existing.address}. Pass force=true to replace it.`,
+              text: `A mailbox already exists: ${result.existing}. Pass force=true to replace it.`,
             },
           ],
         };
       }
-      const api = new SmailsAPI();
-      const result = await api.createMailbox(domain);
-      saveConfig({ address: result.address, token: result.token });
       return { content: [{ type: "text", text: `Mailbox created: ${result.address}` }] };
     },
   );
diff --git a/frontend/app/components/content.tsx b/frontend/app/components/content.tsx
new file mode 100644
index 0000000..2553b79
--- /dev/null
+++ b/frontend/app/components/content.tsx
@@ -0,0 +1,112 @@
+import { ArrowLeft, ArrowUpRight, Check } from "lucide-react";
+import type { ReactNode } from "react";
+import { Link } from "react-router";
+import { GITHUB_URL } from "~/components/site-chrome";
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from "~/components/ui/accordion";
+import { Button } from "~/components/ui/button";
+import { Card } from "~/components/ui/card";
+import type { FaqItem } from "~/lib/seo";
+
+/**
+ * A schema.org JSON-LD <script> for the given @graph. Nodes are built with the
+ * helpers in ~/lib/seo (breadcrumbList, faqPage, …) plus a per-page article node.
+ */
+export function JsonLd({ graph }: { graph: unknown[] }) {
+  const data = { "@context": "https://schema.org", "@graph": graph };
+  return (
+    // biome-ignore lint/security/noDangerouslySetInnerHtml: trusted JSON-LD built from static data
+    <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }} />
+  );
+}
+
+/** Top-of-page breadcrumb: smails / <label>. */
+export function Breadcrumb({ label }: { label: string }) {
+  return (
+    <nav aria-label="Breadcrumb" className="pt-10 text-xs text-muted-foreground">
+      <Link to="/" className="inline-flex items-center gap-1 hover:text-foreground">
+        <ArrowLeft className="size-3" />
+        smails
+      </Link>
+      <span className="mx-2">/</span>
+      <span className="text-foreground">{label}</span>
+    </nav>
+  );
+}
+
+/** Bulleted list with a success check mark per item. */
+export function CheckList({ items }: { items: string[] }) {
+  return (
+    <ul className="mt-6 space-y-3">
+      {items.map((item) => (
+        <li key={item} className="flex gap-3 text-sm sm:text-base">
+          <Check className="mt-0.5 size-4 shrink-0 text-success" />
+          <span className="text-muted-foreground">{item}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/** Numbered (1, 2, 3 …) ordered list of steps. */
+export function NumberedSteps({ items }: { items: string[] }) {
+  return (
+    <ol className="mt-6 space-y-4">
+      {items.map((step, i) => (
+        <li key={step} className="flex gap-4">
+          <span className="flex size-7 shrink-0 items-center justify-center rounded-full bg-muted font-mono text-xs font-medium">
+            {i + 1}
+          </span>
+          <p className="pt-1 text-sm text-muted-foreground sm:text-base">{step}</p>
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+/** The "FAQ" section with an accordion of question/answer items. */
+export function FaqSection({ items }: { items: FaqItem[] }) {
+  return (
+    <section className="pt-16 sm:pt-20">
+      <h2 className="text-2xl font-semibold tracking-tight">FAQ</h2>
+      <Card className="mt-6 gap-0 p-0">
+        <Accordion multiple={false} className="w-full">
+          {items.map((item) => (
+            <AccordionItem key={item.q} value={item.q} className="px-5">
+              <AccordionTrigger>{item.q}</AccordionTrigger>
+              <AccordionContent className="text-muted-foreground">{item.a}</AccordionContent>
+            </AccordionItem>
+          ))}
+        </Accordion>
+      </Card>
+    </section>
+  );
+}
+
+/** Closing call-to-action card with the fixed Open-smails / GitHub buttons. */
+export function CtaSection({ title, children }: { title: string; children: ReactNode }) {
+  return (
+    <section className="pt-16 pb-8 sm:pt-20">
+      <Card className="flex flex-col items-center gap-4 p-8 text-center">
+        <h2 className="text-xl font-semibold tracking-tight">{title}</h2>
+        <p className="max-w-md text-sm text-muted-foreground">{children}</p>
+        <div className="flex flex-wrap justify-center gap-3">
+          <Button render={<Link to="/" />}>Open smails</Button>
+          <Button
+            variant="outline"
+            render={
+              <a href={GITHUB_URL} target="_blank" rel="noreferrer">
+                GitHub
+                <ArrowUpRight />
+              </a>
+            }
+          />
+        </div>
+      </Card>
+    </section>
+  );
+}
diff --git a/frontend/app/hooks/use-websocket.ts b/frontend/app/hooks/use-websocket.ts
index 1f228c7..f821b1c 100644
--- a/frontend/app/hooks/use-websocket.ts
+++ b/frontend/app/hooks/use-websocket.ts
@@ -2,6 +2,20 @@ import { useCallback, useEffect, useRef, useState } from "react";
 
 export type WsStatus = "connecting" | "connected" | "disconnected";
 
+/**
+ * Close a socket we're intentionally replacing/disposing, detaching its handlers
+ * first so its async `onclose` can't mutate shared state (status, ping timer,
+ * reconnect) for the socket that replaced it — e.g. when the mailbox changes.
+ */
+function detachAndClose(ws: WebSocket | null) {
+  if (!ws) return;
+  ws.onopen = null;
+  ws.onmessage = null;
+  ws.onclose = null;
+  ws.onerror = null;
+  ws.close();
+}
+
 interface UseWebSocketOptions {
   url: string | null;
   onMessage?: (data: unknown) => void;
@@ -47,7 +61,7 @@ export function useWebSocket({
     const currentUrl = urlRef.current;
     if (!currentUrl || disposedRef.current) return;
 
-    wsRef.current?.close();
+    detachAndClose(wsRef.current);
     setStatus("connecting");
 
     const ws = new WebSocket(currentUrl);
@@ -88,28 +102,28 @@ export function useWebSocket({
     wsRef.current = ws;
   }, [maxRetries, startPing, stopPing]);
 
-  const disconnect = useCallback(() => {
+  // Reset the whole socket lifecycle (timers, ping, handlers, ref). Used by both
+  // disconnect() and the effect cleanup so the teardown steps can't drift apart.
+  const teardown = useCallback(() => {
+    disposedRef.current = true;
     clearTimeout(timerRef.current);
     stopPing();
-    disposedRef.current = true;
-    wsRef.current?.close();
+    detachAndClose(wsRef.current);
     wsRef.current = null;
-    setStatus("disconnected");
   }, [stopPing]);
 
+  const disconnect = useCallback(() => {
+    teardown();
+    setStatus("disconnected");
+  }, [teardown]);
+
   // biome-ignore lint/correctness/useExhaustiveDependencies: `url` must stay so the effect re-runs and reconnects when the URL changes
   useEffect(() => {
     disposedRef.current = false;
     retriesRef.current = 0;
     connect();
-    return () => {
-      disposedRef.current = true;
-      clearTimeout(timerRef.current);
-      stopPing();
-      wsRef.current?.close();
-      wsRef.current = null;
-    };
-  }, [url, connect, stopPing]);
+    return teardown;
+  }, [url, connect, teardown]);
 
   return { status, reconnect: connect, disconnect };
 }
diff --git a/frontend/app/lib/api.ts b/frontend/app/lib/api.ts
index e4a2b37..3264f45 100644
--- a/frontend/app/lib/api.ts
+++ b/frontend/app/lib/api.ts
@@ -1,4 +1,4 @@
-export interface Email {
+export interface Message {
   id: string;
   from_addr: string;
   from_name: string;
@@ -8,7 +8,15 @@ export interface Email {
   read: number;
 }
 
-export interface EmailDetail extends Email {
+// The detail endpoint returns the parsed body instead of the list preview, so
+// MessageDetail declares its own fields rather than inheriting `preview`.
+export interface MessageDetail {
+  id: string;
+  from_addr: string;
+  from_name: string;
+  subject: string;
+  received_at: number;
+  read: number;
   html: string | null;
   text: string | null;
   attachments: unknown[];
@@ -17,22 +25,74 @@ export interface EmailDetail extends Email {
 const TOKEN_KEY = "smails_token";
 const ADDRESS_KEY = "smails_address";
 
+// In-memory fallback so the session still works when localStorage is unavailable
+// (Safari private mode, storage disabled, or quota exceeded) instead of throwing.
+let memToken: string | null = null;
+let memAddress: string | null = null;
+
+function readStored(key: string): string | null {
+  try {
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+// Prefer the in-memory copy: it's set on every saveAuth, so it always holds the
+// freshest credentials. When a localStorage write has failed (quota / private
+// mode) storage may still hold a stale value, so reading memory first avoids
+// authenticating against the old mailbox. Fall back to storage only on a fresh
+// page load, where memory is empty and the persisted value is all we have.
 export function getToken(): string | null {
-  return localStorage.getItem(TOKEN_KEY);
+  return memToken ?? readStored(TOKEN_KEY);
 }
 
 export function getAddress(): string | null {
-  return localStorage.getItem(ADDRESS_KEY);
+  return memAddress ?? readStored(ADDRESS_KEY);
 }
 
 function saveAuth(address: string, token: string) {
-  localStorage.setItem(TOKEN_KEY, token);
-  localStorage.setItem(ADDRESS_KEY, address);
+  memToken = token;
+  memAddress = address;
+  try {
+    localStorage.setItem(TOKEN_KEY, token);
+    localStorage.setItem(ADDRESS_KEY, address);
+  } catch {
+    // keep the in-memory copy; persistence is best-effort
+  }
 }
 
 export function clearAuth() {
-  localStorage.removeItem(TOKEN_KEY);
-  localStorage.removeItem(ADDRESS_KEY);
+  memToken = null;
+  memAddress = null;
+  try {
+    localStorage.removeItem(TOKEN_KEY);
+    localStorage.removeItem(ADDRESS_KEY);
+  } catch {
+    // already cleared in memory
+  }
+}
+
+const VERSION_HEADER = "X-Smails-Version";
+let serverVersion: string | null = null;
+let onUpdate: (() => void) | null = null;
+
+/** Register a callback fired once when the backend deploy id changes mid-session. */
+export function onServerUpdate(cb: () => void) {
+  onUpdate = cb;
+}
+
+// Compare the deploy id stamped on each API response against the one first seen
+// this session; a change means the backend was redeployed and this tab is stale.
+function checkVersion(res: Response) {
+  const version = res.headers.get(VERSION_HEADER);
+  if (!version) return;
+  if (serverVersion === null) {
+    serverVersion = version;
+  } else if (version !== serverVersion) {
+    serverVersion = version;
+    onUpdate?.();
+  }
 }
 
 async function request<T>(path: string, options: RequestInit = {}): Promise<T> {
@@ -44,9 +104,12 @@ async function request<T>(path: string, options: RequestInit = {}): Promise<T> {
     headers.Authorization = `Bearer ${token}`;
   }
   const res = await fetch(path, { ...options, headers });
+  checkVersion(res);
   if (!res.ok) {
     const body = (await res.json().catch(() => ({ error: res.statusText }))) as { error?: string };
-    throw new Error(body.error || `HTTP ${res.status}`);
+    const error = new Error(body.error || `HTTP ${res.status}`) as Error & { status?: number };
+    error.status = res.status;
+    throw error;
   }
   return res.json() as Promise<T>;
 }
@@ -61,14 +124,14 @@ export async function createMailbox(domain?: string): Promise<{ address: string;
   return result;
 }
 
-export async function listMessages(): Promise<Email[]> {
-  return request<Email[]>("/api/mailbox/messages");
+export async function listMessages(): Promise<Message[]> {
+  return request<Message[]>("/api/mailbox/messages");
 }
 
-export async function getMessage(id: string): Promise<EmailDetail> {
-  return request<EmailDetail>(`/api/mailbox/messages/${id}`);
+export async function getMessage(id: string): Promise<MessageDetail> {
+  return request<MessageDetail>(`/api/mailbox/messages/${encodeURIComponent(id)}`);
 }
 
 export async function deleteMessage(id: string): Promise<void> {
-  await request(`/api/mailbox/messages/${id}`, { method: "DELETE" });
+  await request(`/api/mailbox/messages/${encodeURIComponent(id)}`, { method: "DELETE" });
 }
diff --git a/frontend/app/lib/seo.ts b/frontend/app/lib/seo.ts
new file mode 100644
index 0000000..1daafee
--- /dev/null
+++ b/frontend/app/lib/seo.ts
@@ -0,0 +1,62 @@
+import type { MetaDescriptor } from "react-router";
+
+const OG_IMAGE = "https://smails.dev/og.png";
+
+/** The shared title/OpenGraph/Twitter meta tags for a content page. */
+export function pageMeta({
+  url,
+  title,
+  description,
+  imageAlt,
+}: {
+  url: string;
+  title: string;
+  description: string;
+  imageAlt: string;
+}): MetaDescriptor[] {
+  return [
+    { title },
+    { name: "description", content: description },
+    { tagName: "link", rel: "canonical", href: url },
+    { property: "og:type", content: "article" },
+    { property: "og:url", content: url },
+    { property: "og:site_name", content: "smails" },
+    { property: "og:title", content: title },
+    { property: "og:description", content: description },
+    { property: "og:image", content: OG_IMAGE },
+    { property: "og:image:width", content: "1200" },
+    { property: "og:image:height", content: "630" },
+    { property: "og:image:alt", content: imageAlt },
+    { name: "twitter:card", content: "summary_large_image" },
+    { name: "twitter:title", content: title },
+    { name: "twitter:description", content: description },
+    { name: "twitter:image", content: OG_IMAGE },
+  ];
+}
+
+export interface FaqItem {
+  q: string;
+  a: string;
+}
+
+// schema.org JSON-LD @graph node builders, shared by the content pages.
+export function breadcrumbList(name: string, url: string) {
+  return {
+    "@type": "BreadcrumbList",
+    itemListElement: [
+      { "@type": "ListItem", position: 1, name: "smails", item: "https://smails.dev/" },
+      { "@type": "ListItem", position: 2, name, item: url },
+    ],
+  };
+}
+
+export function faqPage(items: FaqItem[]) {
+  return {
+    "@type": "FAQPage",
+    mainEntity: items.map((item) => ({
+      "@type": "Question",
+      name: item.q,
+      acceptedAnswer: { "@type": "Answer", text: item.a },
+    })),
+  };
+}
diff --git a/frontend/app/routes/api.tsx b/frontend/app/routes/api.tsx
index e87d1c1..3bb8833 100644
--- a/frontend/app/routes/api.tsx
+++ b/frontend/app/routes/api.tsx
@@ -1,37 +1,22 @@
-import { ArrowLeft, ArrowUpRight, Check } from "lucide-react";
 import { Link } from "react-router";
 import { CodeBlock } from "~/components/code-block";
-import { ContentNav, GITHUB_URL, SiteFooter } from "~/components/site-chrome";
+import { Breadcrumb, CheckList, CtaSection, JsonLd } from "~/components/content";
+import { ContentNav, SiteFooter } from "~/components/site-chrome";
 import { Badge } from "~/components/ui/badge";
 import { Button } from "~/components/ui/button";
 import { Card } from "~/components/ui/card";
+import { breadcrumbList, pageMeta } from "~/lib/seo";
 import { cn } from "~/lib/utils";
 import type { Route } from "./+types/api";
 
 export function meta(_: Route.MetaArgs) {
-  const url = "https://smails.dev/email-api";
-  const title = "Free disposable email REST API — no signup, no API key | smails";
-  const description =
-    "A free disposable email REST API: create a mailbox and read incoming messages programmatically. No signup, no API key — one POST returns an address and token. Stream new mail over WebSocket. Built for scripts and AI agents. Receive-only.";
-  const image = "https://smails.dev/og.png";
-  return [
-    { title },
-    { name: "description", content: description },
-    { tagName: "link", rel: "canonical", href: url },
-    { property: "og:type", content: "article" },
-    { property: "og:url", content: url },
-    { property: "og:site_name", content: "smails" },
-    { property: "og:title", content: title },
-    { property: "og:description", content: description },
-    { property: "og:image", content: image },
-    { property: "og:image:width", content: "1200" },
-    { property: "og:image:height", content: "630" },
-    { property: "og:image:alt", content: "smails — free disposable email REST API" },
-    { name: "twitter:card", content: "summary_large_image" },
-    { name: "twitter:title", content: title },
-    { name: "twitter:description", content: description },
-    { name: "twitter:image", content: image },
-  ];
+  return pageMeta({
+    url: "https://smails.dev/email-api",
+    title: "Free disposable email REST API — no signup, no API key | smails",
+    description:
+      "A free disposable email REST API: create a mailbox and read incoming messages programmatically. No signup, no API key — one POST returns an address and token. Stream new mail over WebSocket. Built for scripts and AI agents. Receive-only.",
+    imageAlt: "smails — free disposable email REST API",
+  });
 }
 
 const DIFFERENTIATORS = [
@@ -43,7 +28,10 @@ const DIFFERENTIATORS = [
 
 const CREATE_CODE = `# create a mailbox — no auth, no key
 curl -X POST https://smails.dev/api/mailbox
-# → { "address": "a8f3@smails.dev", "token": "a8f3@smails.dev.s3cr3t" }`;
+# → {
+#   "address": "cool-fox-7a3f9c@smails.dev",
+#   "token": "cool-fox-7a3f9c.5f3a9c2e8b1d4a7c6e0f2b9d8a1c3e5f"
+# }`;
 
 const READ_CODE = `# list messages with the returned token
 curl https://smails.dev/api/mailbox/messages \\
@@ -59,7 +47,7 @@ const ws = new WebSocket(
 );
 ws.onmessage = (e) => {
   const msg = JSON.parse(e.data);
-  if (msg.type === "new_email") fetchMessages();
+  if (msg.type === "new_message") fetchMessages();
 };`;
 
 const ENDPOINTS: { method: string; path: string; desc: string; auth: boolean }[] = [
@@ -88,18 +76,23 @@ const ENDPOINTS: { method: string; path: string; desc: string; auth: boolean }[]
 export default function Api() {
   return (
     <div className="flex min-h-dvh flex-col bg-background text-foreground">
-      <StructuredData />
+      <JsonLd
+        graph={[
+          {
+            "@type": "TechArticle",
+            headline: "A free disposable email REST API, no key required",
+            description:
+              "Create a disposable mailbox and read incoming messages programmatically with a free REST API — no signup, no API key. Poll or stream over WebSocket. Built for scripts and AI agents.",
+            about: "Disposable email REST API",
+            url: "https://smails.dev/email-api",
+          },
+          breadcrumbList("REST API", "https://smails.dev/email-api"),
+        ]}
+      />
       <ContentNav current="api" />
 
       <main className="mx-auto w-full max-w-3xl flex-1 px-5">
-        <nav aria-label="Breadcrumb" className="pt-10 text-xs text-muted-foreground">
-          <Link to="/" className="inline-flex items-center gap-1 hover:text-foreground">
-            <ArrowLeft className="size-3" />
-            smails
-          </Link>
-          <span className="mx-2">/</span>
-          <span className="text-foreground">REST API</span>
-        </nav>
+        <Breadcrumb label="REST API" />
 
         <header className="pt-8 sm:pt-12">
           <Badge variant="secondary">REST API · Free · No API key · No signup</Badge>
@@ -122,14 +115,7 @@ export default function Api() {
 
         <section className="pt-16 sm:pt-20">
           <h2 className="text-2xl font-semibold tracking-tight">Why this one</h2>
-          <ul className="mt-6 space-y-3">
-            {DIFFERENTIATORS.map((d) => (
-              <li key={d} className="flex gap-3 text-sm sm:text-base">
-                <Check className="mt-0.5 size-4 shrink-0 text-success" />
-                <span className="text-muted-foreground">{d}</span>
-              </li>
-            ))}
-          </ul>
+          <CheckList items={DIFFERENTIATORS} />
         </section>
 
         <section id="quickstart" className="scroll-mt-16 pt-16 sm:pt-20">
@@ -176,9 +162,8 @@ export default function Api() {
           </Card>
           <p className="mt-4 text-sm text-muted-foreground">
             Authenticate every request except create with{" "}
-            <code className="font-mono">Authorization: Bearer &lt;token&gt;</code>. The token is{" "}
-            <code className="font-mono">{"{address}.{secret}"}</code> — keep it; it's the only way
-            back into the mailbox.
+            <code className="font-mono">Authorization: Bearer &lt;token&gt;</code>. Keep the
+            returned token — it's the only credential for the mailbox.
           </p>
         </section>
 
@@ -202,69 +187,20 @@ export default function Api() {
           </div>
         </section>
 
-        <section className="pt-16 pb-8 sm:pt-20">
-          <Card className="flex flex-col items-center gap-4 p-8 text-center">
-            <h2 className="text-xl font-semibold tracking-tight">Build with it.</h2>
-            <p className="max-w-md text-sm text-muted-foreground">
-              Extracting a code in an agent? See{" "}
-              <Link to="/otp" className="font-medium text-foreground underline underline-offset-4">
-                reading verification codes
-              </Link>
-              , or plug in the{" "}
-              <Link to="/mcp" className="font-medium text-foreground underline underline-offset-4">
-                MCP server
-              </Link>
-              .
-            </p>
-            <div className="flex flex-wrap justify-center gap-3">
-              <Button render={<Link to="/" />}>Open smails</Button>
-              <Button
-                variant="outline"
-                render={
-                  <a href={GITHUB_URL} target="_blank" rel="noreferrer">
-                    GitHub
-                    <ArrowUpRight />
-                  </a>
-                }
-              />
-            </div>
-          </Card>
-        </section>
+        <CtaSection title="Build with it.">
+          Extracting a code in an agent? See{" "}
+          <Link to="/otp" className="font-medium text-foreground underline underline-offset-4">
+            reading verification codes
+          </Link>
+          , or plug in the{" "}
+          <Link to="/mcp" className="font-medium text-foreground underline underline-offset-4">
+            MCP server
+          </Link>
+          .
+        </CtaSection>
       </main>
 
       <SiteFooter />
     </div>
   );
 }
-
-function StructuredData() {
-  const data = {
-    "@context": "https://schema.org",
-    "@graph": [
-      {
-        "@type": "TechArticle",
-        headline: "A free disposable email REST API, no key required",
-        description:
-          "Create a disposable mailbox and read incoming messages programmatically with a free REST API — no signup, no API key. Poll or stream over WebSocket. Built for scripts and AI agents.",
-        about: "Disposable email REST API",
-        url: "https://smails.dev/email-api",
-      },
-      {
-        "@type": "BreadcrumbList",
-        itemListElement: [
-          { "@type": "ListItem", position: 1, name: "smails", item: "https://smails.dev/" },
-          {
-            "@type": "ListItem",
-            position: 2,
-            name: "REST API",
-            item: "https://smails.dev/email-api",
-          },
-        ],
-      },
-    ],
-  };
-  return (
-    // biome-ignore lint/security/noDangerouslySetInnerHtml: trusted JSON-LD built from static data
-    <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }} />
-  );
-}
diff --git a/frontend/app/routes/home.tsx b/frontend/app/routes/home.tsx
index 0c1e715..bb84c03 100644
--- a/frontend/app/routes/home.tsx
+++ b/frontend/app/routes/home.tsx
@@ -1,8 +1,9 @@
 import { ArrowDown, ArrowLeft, Copy, Plus, RefreshCw, Trash2 } from "lucide-react";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { Link } from "react-router";
 import { toast } from "sonner";
 import { CodeBlock } from "~/components/code-block";
+import { JsonLd } from "~/components/content";
 import { GITHUB_URL, SiteFooter } from "~/components/site-chrome";
 import {
   Accordion,
@@ -22,14 +23,16 @@ import {
   clearAuth,
   createMailbox,
   deleteMessage,
-  type Email,
-  type EmailDetail as EmailDetailType,
   getAddress,
   getMessage,
   getToken,
   listMessages,
+  type Message,
+  type MessageDetail as MessageDetailType,
+  onServerUpdate,
 } from "~/lib/api";
 import { formatTime, initials } from "~/lib/format";
+import { faqPage } from "~/lib/seo";
 import { cn } from "~/lib/utils";
 import type { Route } from "./+types/home";
 
@@ -135,9 +138,9 @@ function buildWsUrl(token: string | null): string | null {
 
 export default function Home() {
   const [address, setAddress] = useState<string>("");
-  const [emails, setEmails] = useState<Email[]>([]);
+  const [messages, setMessages] = useState<Message[]>([]);
   const [selectedId, setSelectedId] = useState<string | null>(null);
-  const [detail, setDetail] = useState<EmailDetailType | null>(null);
+  const [detail, setDetail] = useState<MessageDetailType | null>(null);
   const [token, setToken] = useState<string | null>(null);
   const [loaded, setLoaded] = useState(false);
   const selectedIdRef = useRef<string | null>(null);
@@ -145,10 +148,10 @@ export default function Home() {
 
   const fetchMessages = useCallback(async () => {
     const msgs = await listMessages();
-    setEmails(msgs);
+    setMessages(msgs);
   }, []);
 
-  const wsUrl = useMemo(() => buildWsUrl(token), [token]);
+  const wsUrl = buildWsUrl(token);
 
   const { status: wsStatus } = useWebSocket({
     url: wsUrl,
@@ -157,7 +160,7 @@ export default function Home() {
         data &&
         typeof data === "object" &&
         "type" in data &&
-        (data as { type: string }).type === "new_email"
+        (data as { type: string }).type === "new_message"
       ) {
         fetchMessages();
       }
@@ -171,13 +174,21 @@ export default function Home() {
         const addr = getAddress();
         let needsNewMailbox = !existingToken || !addr;
         if (existingToken && addr) {
+          setAddress(addr);
+          setToken(existingToken);
           try {
-            setAddress(addr);
-            setToken(existingToken);
             await fetchMessages();
-          } catch {
-            clearAuth();
-            needsNewMailbox = true;
+          } catch (err) {
+            // Only discard the saved mailbox when the token is actually
+            // rejected. A transient network/server error must NOT wipe the
+            // user's address — keep it and let them retry.
+            const status = (err as { status?: number })?.status;
+            if (status === 401 || status === 403) {
+              clearAuth();
+              needsNewMailbox = true;
+            } else {
+              toast.error("Couldn't load messages — pull to refresh.");
+            }
           }
         }
         if (needsNewMailbox) {
@@ -194,8 +205,18 @@ export default function Home() {
     init();
   }, [fetchMessages]);
 
-  const selected = emails.find((e) => e.id === selectedId) ?? null;
-  const unreadCount = emails.filter((e) => !e.read).length;
+  useEffect(() => {
+    onServerUpdate(() => {
+      toast("A new version is available.", {
+        id: "app-update",
+        duration: Number.POSITIVE_INFINITY,
+        action: { label: "Refresh", onClick: () => window.location.reload() },
+      });
+    });
+  }, []);
+
+  const selected = messages.find((m) => m.id === selectedId) ?? null;
+  const unreadCount = messages.filter((m) => !m.read).length;
 
   function copyAddress() {
     navigator.clipboard.writeText(address).then(
@@ -209,7 +230,7 @@ export default function Home() {
       const result = await createMailbox();
       setAddress(result.address);
       setToken(result.token);
-      setEmails([]);
+      setMessages([]);
       setSelectedId(null);
       setDetail(null);
       toast.success("New mailbox created");
@@ -227,12 +248,13 @@ export default function Home() {
     }
   }
 
-  async function openEmail(email: Email) {
-    const targetId = email.id;
+  async function openMessage(message: Message) {
+    const targetId = message.id;
+    const wasUnread = !message.read;
     setSelectedId(targetId);
     setDetail(null);
-    if (!email.read) {
-      setEmails((prev) => prev.map((e) => (e.id === targetId ? { ...e, read: 1 } : e)));
+    if (wasUnread) {
+      setMessages((prev) => prev.map((m) => (m.id === targetId ? { ...m, read: 1 } : m)));
     }
     try {
       const msg = await getMessage(targetId);
@@ -240,6 +262,10 @@ export default function Home() {
         setDetail(msg);
       }
     } catch {
+      // Roll back the optimistic "read" if the message never loaded.
+      if (wasUnread) {
+        setMessages((prev) => prev.map((m) => (m.id === targetId ? { ...m, read: 0 } : m)));
+      }
       toast.error("Failed to load message");
     }
   }
@@ -247,7 +273,7 @@ export default function Home() {
   async function handleDelete(id: string) {
     try {
       await deleteMessage(id);
-      setEmails((prev) => prev.filter((e) => e.id !== id));
+      setMessages((prev) => prev.filter((m) => m.id !== id));
       if (selectedIdRef.current === id) {
         setSelectedId(null);
         setDetail(null);
@@ -260,7 +286,20 @@ export default function Home() {
 
   return (
     <div className="flex min-h-dvh flex-col bg-background text-foreground">
-      <StructuredData />
+      <JsonLd
+        graph={[
+          {
+            "@type": "WebApplication",
+            name: "smails",
+            applicationCategory: "CommunicationApplication",
+            operatingSystem: "Web",
+            description:
+              "A free disposable email address with a REST API, CLI, and MCP server. Receive emails in real time with no sign-up.",
+            offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
+          },
+          faqPage(FAQ),
+        ]}
+      />
       <Nav />
 
       <main className="mx-auto w-full max-w-5xl flex-1 px-5">
@@ -284,7 +323,7 @@ export default function Home() {
         <section id="inbox" aria-labelledby="inbox-heading" className="scroll-mt-16 pt-12 sm:pt-16">
           <Mailbox
             address={address}
-            emails={emails}
+            messages={messages}
             loading={!loaded}
             selected={selected}
             detail={detail}
@@ -294,7 +333,7 @@ export default function Home() {
             onNew={handleNewAddress}
             onRefresh={handleRefresh}
             onCopy={copyAddress}
-            onOpen={openEmail}
+            onOpen={openMessage}
             onBack={() => {
               setSelectedId(null);
               setDetail(null);
@@ -347,7 +386,7 @@ function Nav() {
 
 function Mailbox({
   address,
-  emails,
+  messages,
   loading,
   selected,
   detail,
@@ -362,17 +401,17 @@ function Mailbox({
   onDelete,
 }: {
   address: string;
-  emails: Email[];
+  messages: Message[];
   loading: boolean;
-  selected: Email | null;
-  detail: EmailDetailType | null;
+  selected: Message | null;
+  detail: MessageDetailType | null;
   selectedId: string | null;
   unreadCount: number;
   wsStatus: WsStatus;
   onNew: () => void;
   onRefresh: () => void;
   onCopy: () => void;
-  onOpen: (e: Email) => void;
+  onOpen: (m: Message) => void;
   onBack: () => void;
   onDelete: (id: string) => void;
 }) {
@@ -406,7 +445,7 @@ function Mailbox({
 
       <div className="flex items-center justify-between border-b border-border px-4 py-2.5">
         <span className="text-xs text-muted-foreground">
-          {emails.length} message{emails.length === 1 ? "" : "s"}
+          {messages.length} message{messages.length === 1 ? "" : "s"}
           {unreadCount > 0 && <span className="text-foreground"> · {unreadCount} unread</span>}
         </span>
         <span className="flex items-center gap-1.5 text-xs text-muted-foreground">
@@ -437,16 +476,16 @@ function Mailbox({
                   <SkeletonRow key={i} />
                 ))}
               </ul>
-            ) : emails.length === 0 ? (
+            ) : messages.length === 0 ? (
               <EmptyInbox />
             ) : (
               <ul className="divide-y divide-border">
-                {emails.map((email) => (
-                  <EmailListItem
-                    key={email.id}
-                    email={email}
-                    active={email.id === selectedId}
-                    onClick={() => onOpen(email)}
+                {messages.map((message) => (
+                  <MessageListItem
+                    key={message.id}
+                    message={message}
+                    active={message.id === selectedId}
+                    onClick={() => onOpen(message)}
                   />
                 ))}
               </ul>
@@ -456,8 +495,8 @@ function Mailbox({
 
         <section className={cn("min-h-0 min-w-0", !selected && "hidden md:block")}>
           {selected ? (
-            <EmailDetail
-              email={selected}
+            <MessageDetail
+              message={selected}
               detail={detail}
               onBack={onBack}
               onDelete={() => onDelete(selected.id)}
@@ -581,16 +620,16 @@ function Faq() {
   );
 }
 
-function EmailListItem({
-  email,
+function MessageListItem({
+  message,
   active,
   onClick,
 }: {
-  email: Email;
+  message: Message;
   active: boolean;
   onClick: () => void;
 }) {
-  const isRead = !!email.read;
+  const isRead = !!message.read;
   return (
     <li>
       <button
@@ -602,7 +641,7 @@ function EmailListItem({
         )}
       >
         <Avatar className="mt-0.5 size-8 shrink-0">
-          <AvatarFallback>{initials(email.from_name)}</AvatarFallback>
+          <AvatarFallback>{initials(message.from_name)}</AvatarFallback>
         </Avatar>
         <div className="min-w-0 flex-1">
           <div className="flex items-baseline justify-between gap-2">
@@ -610,14 +649,14 @@ function EmailListItem({
               className={cn("truncate text-sm", isRead ? "text-muted-foreground" : "font-semibold")}
             >
               {!isRead && <span className="sr-only">Unread. </span>}
-              {email.from_name}
+              {message.from_name}
             </span>
             <span className="shrink-0 text-xs text-muted-foreground">
-              {formatTime(email.received_at)}
+              {formatTime(message.received_at)}
             </span>
           </div>
-          <p className={cn("truncate text-sm", !isRead && "font-medium")}>{email.subject}</p>
-          <p className="truncate text-xs text-muted-foreground">{email.preview}</p>
+          <p className={cn("truncate text-sm", !isRead && "font-medium")}>{message.subject}</p>
+          <p className="truncate text-xs text-muted-foreground">{message.preview}</p>
         </div>
         {!isRead && (
           <span
@@ -630,14 +669,14 @@ function EmailListItem({
   );
 }
 
-function EmailDetail({
-  email,
+function MessageDetail({
+  message,
   detail,
   onBack,
   onDelete,
 }: {
-  email: Email;
-  detail: EmailDetailType | null;
+  message: Message;
+  detail: MessageDetailType | null;
   onBack: () => void;
   onDelete: () => void;
 }) {
@@ -653,21 +692,21 @@ function EmailDetail({
         >
           <ArrowLeft />
         </Button>
-        <h2 className="min-w-0 flex-1 truncate text-sm font-semibold">{email.subject}</h2>
+        <h2 className="min-w-0 flex-1 truncate text-sm font-semibold">{message.subject}</h2>
         <IconAction label="Delete" onClick={onDelete}>
           <Trash2 />
         </IconAction>
       </div>
       <div className="flex items-center gap-3 border-b border-border px-4 py-3.5">
         <Avatar className="size-9">
-          <AvatarFallback>{initials(email.from_name)}</AvatarFallback>
+          <AvatarFallback>{initials(message.from_name)}</AvatarFallback>
         </Avatar>
         <div className="min-w-0">
-          <p className="truncate text-sm font-medium">{email.from_name}</p>
-          <p className="truncate text-xs text-muted-foreground">{email.from_addr}</p>
+          <p className="truncate text-sm font-medium">{message.from_name}</p>
+          <p className="truncate text-xs text-muted-foreground">{message.from_addr}</p>
         </div>
         <span className="ml-auto shrink-0 text-xs text-muted-foreground">
-          {formatTime(email.received_at)}
+          {formatTime(message.received_at)}
         </span>
       </div>
       <div className="min-h-0 flex-1">
@@ -675,7 +714,7 @@ function EmailDetail({
           <iframe
             sandbox="allow-popups allow-popups-to-escape-sandbox"
             srcDoc={`<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; img-src data: cid:;">${detail.html}`}
-            title="Email content"
+            title="Message content"
             className="h-full w-full border-0"
           />
         ) : (
@@ -750,32 +789,3 @@ function GithubIcon({ className }: { className?: string }) {
     </svg>
   );
 }
-
-function StructuredData() {
-  const data = {
-    "@context": "https://schema.org",
-    "@graph": [
-      {
-        "@type": "WebApplication",
-        name: "smails",
-        applicationCategory: "CommunicationApplication",
-        operatingSystem: "Web",
-        description:
-          "A free disposable email address with a REST API, CLI, and MCP server. Receive emails in real time with no sign-up.",
-        offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
-      },
-      {
-        "@type": "FAQPage",
-        mainEntity: FAQ.map((item) => ({
-          "@type": "Question",
-          name: item.q,
-          acceptedAnswer: { "@type": "Answer", text: item.a },
-        })),
-      },
-    ],
-  };
-  return (
-    // biome-ignore lint/security/noDangerouslySetInnerHtml: trusted JSON-LD built from static data
-    <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }} />
-  );
-}
diff --git a/frontend/app/routes/mcp.tsx b/frontend/app/routes/mcp.tsx
index 3d648e6..30e6c6b 100644
--- a/frontend/app/routes/mcp.tsx
+++ b/frontend/app/routes/mcp.tsx
@@ -1,45 +1,28 @@
-import { ArrowLeft, ArrowUpRight, Check } from "lucide-react";
 import { Link } from "react-router";
 import { CodeBlock } from "~/components/code-block";
-import { ContentNav, GITHUB_URL, SiteFooter } from "~/components/site-chrome";
 import {
-  Accordion,
-  AccordionContent,
-  AccordionItem,
-  AccordionTrigger,
-} from "~/components/ui/accordion";
+  Breadcrumb,
+  CheckList,
+  CtaSection,
+  FaqSection,
+  JsonLd,
+  NumberedSteps,
+} from "~/components/content";
+import { ContentNav, SiteFooter } from "~/components/site-chrome";
 import { Badge } from "~/components/ui/badge";
 import { Button } from "~/components/ui/button";
 import { Card } from "~/components/ui/card";
+import { breadcrumbList, faqPage, pageMeta } from "~/lib/seo";
 import type { Route } from "./+types/mcp";
 
 export function meta(_: Route.MetaArgs) {
-  const url = "https://smails.dev/mcp";
-  const title = "Free disposable email MCP server — no API key, no signup | smails";
-  const description =
-    "A free MCP server that gives your AI agent its own disposable inbox — no API key, no signup. Plug it into Claude, Cursor, or any MCP client and the agent creates a mailbox and reads verification codes and magic links on its own. Receive-only.";
-  const image = "https://smails.dev/og.png";
-  return [
-    { title },
-    { name: "description", content: description },
-    { tagName: "link", rel: "canonical", href: url },
-    { property: "og:type", content: "article" },
-    { property: "og:url", content: url },
-    { property: "og:site_name", content: "smails" },
-    { property: "og:title", content: title },
-    { property: "og:description", content: description },
-    { property: "og:image", content: image },
-    { property: "og:image:width", content: "1200" },
-    { property: "og:image:height", content: "630" },
-    {
-      property: "og:image:alt",
-      content: "smails — free disposable email MCP server for AI agents",
-    },
-    { name: "twitter:card", content: "summary_large_image" },
-    { name: "twitter:title", content: title },
-    { name: "twitter:description", content: description },
-    { name: "twitter:image", content: image },
-  ];
+  return pageMeta({
+    url: "https://smails.dev/mcp",
+    title: "Free disposable email MCP server — no API key, no signup | smails",
+    description:
+      "A free MCP server that gives your AI agent its own disposable inbox — no API key, no signup. Plug it into Claude, Cursor, or any MCP client and the agent creates a mailbox and reads verification codes and magic links on its own. Receive-only.",
+    imageAlt: "smails — free disposable email MCP server for AI agents",
+  });
 }
 
 const CLAUDE_CODE_CMD = `claude mcp add smails -- npx -y @smails/cli mcp`;
@@ -108,18 +91,24 @@ const FAQ = [
 export default function Mcp() {
   return (
     <div className="flex min-h-dvh flex-col bg-background text-foreground">
-      <StructuredData />
+      <JsonLd
+        graph={[
+          {
+            "@type": "TechArticle",
+            headline: "A free disposable email MCP server for your AI agent",
+            description:
+              "How to plug the free, no-key smails MCP server into Claude, Cursor, or any MCP client so your agent can create a disposable mailbox and read verification codes on its own.",
+            about: "Model Context Protocol disposable email server",
+            url: "https://smails.dev/mcp",
+          },
+          faqPage(FAQ),
+          breadcrumbList("MCP server", "https://smails.dev/mcp"),
+        ]}
+      />
       <ContentNav current="mcp" />
 
       <main className="mx-auto w-full max-w-3xl flex-1 px-5">
-        <nav aria-label="Breadcrumb" className="pt-10 text-xs text-muted-foreground">
-          <Link to="/" className="inline-flex items-center gap-1 hover:text-foreground">
-            <ArrowLeft className="size-3" />
-            smails
-          </Link>
-          <span className="mx-2">/</span>
-          <span className="text-foreground">MCP server</span>
-        </nav>
+        <Breadcrumb label="MCP server" />
 
         <header className="pt-8 sm:pt-12">
           <Badge variant="secondary">MCP · Free · No API key · No signup</Badge>
@@ -145,14 +134,7 @@ export default function Mcp() {
           <p className="mt-3 text-sm text-muted-foreground sm:text-base">
             Other MCP email servers make you register and pass an API key. smails doesn't.
           </p>
-          <ul className="mt-6 space-y-3">
-            {DIFFERENTIATORS.map((d) => (
-              <li key={d} className="flex gap-3 text-sm sm:text-base">
-                <Check className="mt-0.5 size-4 shrink-0 text-success" />
-                <span className="text-muted-foreground">{d}</span>
-              </li>
-            ))}
-          </ul>
+          <CheckList items={DIFFERENTIATORS} />
         </section>
 
         <section id="setup" className="scroll-mt-16 pt-16 sm:pt-20">
@@ -196,16 +178,7 @@ export default function Mcp() {
           <h2 className="text-2xl font-semibold tracking-tight">
             How an agent reads a verification code
           </h2>
-          <ol className="mt-6 space-y-4">
-            {FLOW.map((step, i) => (
-              <li key={step} className="flex gap-4">
-                <span className="flex size-7 shrink-0 items-center justify-center rounded-full bg-muted font-mono text-xs font-medium">
-                  {i + 1}
-                </span>
-                <p className="pt-1 text-sm text-muted-foreground sm:text-base">{step}</p>
-              </li>
-            ))}
-          </ol>
+          <NumberedSteps items={FLOW} />
           <p className="mt-6 text-sm text-muted-foreground">
             Prefer raw HTTP or a shell? The same flow works over the{" "}
             <Link
@@ -222,79 +195,15 @@ export default function Mcp() {
           </p>
         </section>
 
-        <section className="pt-16 sm:pt-20">
-          <h2 className="text-2xl font-semibold tracking-tight">FAQ</h2>
-          <Card className="mt-6 gap-0 p-0">
-            <Accordion multiple={false} className="w-full">
-              {FAQ.map((item) => (
-                <AccordionItem key={item.q} value={item.q} className="px-5">
-                  <AccordionTrigger>{item.q}</AccordionTrigger>
-                  <AccordionContent className="text-muted-foreground">{item.a}</AccordionContent>
-                </AccordionItem>
-              ))}
-            </Accordion>
-          </Card>
-        </section>
+        <FaqSection items={FAQ} />
 
-        <section className="pt-16 pb-8 sm:pt-20">
-          <Card className="flex flex-col items-center gap-4 p-8 text-center">
-            <h2 className="text-xl font-semibold tracking-tight">Give your agent an inbox.</h2>
-            <p className="max-w-md text-sm text-muted-foreground">
-              Open the web app for a live inbox, or wire up the MCP server above and let your agent
-              handle email itself.
-            </p>
-            <div className="flex flex-wrap justify-center gap-3">
-              <Button render={<Link to="/" />}>Open smails</Button>
-              <Button
-                variant="outline"
-                render={
-                  <a href={GITHUB_URL} target="_blank" rel="noreferrer">
-                    GitHub
-                    <ArrowUpRight />
-                  </a>
-                }
-              />
-            </div>
-          </Card>
-        </section>
+        <CtaSection title="Give your agent an inbox.">
+          Open the web app for a live inbox, or wire up the MCP server above and let your agent
+          handle email itself.
+        </CtaSection>
       </main>
 
       <SiteFooter />
     </div>
   );
 }
-
-function StructuredData() {
-  const data = {
-    "@context": "https://schema.org",
-    "@graph": [
-      {
-        "@type": "TechArticle",
-        headline: "A free disposable email MCP server for your AI agent",
-        description:
-          "How to plug the free, no-key smails MCP server into Claude, Cursor, or any MCP client so your agent can create a disposable mailbox and read verification codes on its own.",
-        about: "Model Context Protocol disposable email server",
-        url: "https://smails.dev/mcp",
-      },
-      {
-        "@type": "FAQPage",
-        mainEntity: FAQ.map((item) => ({
-          "@type": "Question",
-          name: item.q,
-          acceptedAnswer: { "@type": "Answer", text: item.a },
-        })),
-      },
-      {
-        "@type": "BreadcrumbList",
-        itemListElement: [
-          { "@type": "ListItem", position: 1, name: "smails", item: "https://smails.dev/" },
-          { "@type": "ListItem", position: 2, name: "MCP server", item: "https://smails.dev/mcp" },
-        ],
-      },
-    ],
-  };
-  return (
-    // biome-ignore lint/security/noDangerouslySetInnerHtml: trusted JSON-LD built from static data
-    <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }} />
-  );
-}
diff --git a/frontend/app/routes/otp.tsx b/frontend/app/routes/otp.tsx
index db08430..09fe264 100644
--- a/frontend/app/routes/otp.tsx
+++ b/frontend/app/routes/otp.tsx
@@ -1,42 +1,20 @@
-import { ArrowLeft, ArrowUpRight } from "lucide-react";
 import { Link } from "react-router";
 import { CodeBlock } from "~/components/code-block";
-import { ContentNav, GITHUB_URL, SiteFooter } from "~/components/site-chrome";
-import {
-  Accordion,
-  AccordionContent,
-  AccordionItem,
-  AccordionTrigger,
-} from "~/components/ui/accordion";
+import { Breadcrumb, CtaSection, FaqSection, JsonLd, NumberedSteps } from "~/components/content";
+import { ContentNav, SiteFooter } from "~/components/site-chrome";
 import { Badge } from "~/components/ui/badge";
 import { Button } from "~/components/ui/button";
-import { Card } from "~/components/ui/card";
+import { breadcrumbList, faqPage, pageMeta } from "~/lib/seo";
 import type { Route } from "./+types/otp";
 
 export function meta(_: Route.MetaArgs) {
-  const url = "https://smails.dev/otp";
-  const title = "Get verification codes & OTPs from email — API, CLI & MCP | smails";
-  const description =
-    "A free disposable inbox for receiving OTPs, verification codes, and magic links — no signup. Read them from the web, the CLI, the REST API, or an MCP server so a script or AI agent can finish a sign-up on its own. Receive-only.";
-  const image = "https://smails.dev/og.png";
-  return [
-    { title },
-    { name: "description", content: description },
-    { tagName: "link", rel: "canonical", href: url },
-    { property: "og:type", content: "article" },
-    { property: "og:url", content: url },
-    { property: "og:site_name", content: "smails" },
-    { property: "og:title", content: title },
-    { property: "og:description", content: description },
-    { property: "og:image", content: image },
-    { property: "og:image:width", content: "1200" },
-    { property: "og:image:height", content: "630" },
-    { property: "og:image:alt", content: "smails — get verification codes from email" },
-    { name: "twitter:card", content: "summary_large_image" },
-    { name: "twitter:title", content: title },
-    { name: "twitter:description", content: description },
-    { name: "twitter:image", content: image },
-  ];
+  return pageMeta({
+    url: "https://smails.dev/otp",
+    title: "Get verification codes & OTPs from email — API, CLI & MCP | smails",
+    description:
+      "A free disposable inbox for receiving OTPs, verification codes, and magic links — no signup. Read them from the web, the CLI, the REST API, or an MCP server so a script or AI agent can finish a sign-up on its own. Receive-only.",
+    imageAlt: "smails — get verification codes from email",
+  });
 }
 
 const CLI_CODE = `# create a disposable inbox, then read the code
@@ -49,9 +27,10 @@ TOKEN=$(curl -sX POST https://smails.dev/api/mailbox | jq -r .token)
 # ...use the address, then read the latest message:
 curl -s https://smails.dev/api/mailbox/messages \\
   -H "Authorization: Bearer $TOKEN" | jq -r '.[0].id'
-# fetch its body and grep the 6-digit code:
+# fetch its body, then grep the 6-digit code out of it:
 curl -s https://smails.dev/api/mailbox/messages/<id> \\
-  -H "Authorization: Bearer $TOKEN" | grep -oE '[0-9]{6}'`;
+  -H "Authorization: Bearer $TOKEN" \\
+  | jq -r '.text // .html' | grep -oE '\\b[0-9]{6}\\b' | head -1`;
 
 const STEPS = [
   "Create a disposable mailbox — instantly, with no signup.",
@@ -83,18 +62,23 @@ const FAQ = [
 export default function Otp() {
   return (
     <div className="flex min-h-dvh flex-col bg-background text-foreground">
-      <StructuredData />
+      <JsonLd
+        graph={[
+          {
+            "@type": "HowTo",
+            name: "Get a verification code or OTP from email with a disposable inbox",
+            description:
+              "Use a free disposable inbox to receive an OTP, verification code, or magic link and read it from the web, CLI, REST API, or an MCP server.",
+            step: STEPS.map((s, i) => ({ "@type": "HowToStep", position: i + 1, text: s })),
+          },
+          faqPage(FAQ),
+          breadcrumbList("Verification codes", "https://smails.dev/otp"),
+        ]}
+      />
       <ContentNav current="otp" />
 
       <main className="mx-auto w-full max-w-3xl flex-1 px-5">
-        <nav aria-label="Breadcrumb" className="pt-10 text-xs text-muted-foreground">
-          <Link to="/" className="inline-flex items-center gap-1 hover:text-foreground">
-            <ArrowLeft className="size-3" />
-            smails
-          </Link>
-          <span className="mx-2">/</span>
-          <span className="text-foreground">Verification codes</span>
-        </nav>
+        <Breadcrumb label="Verification codes" />
 
         <header className="pt-8 sm:pt-12">
           <Badge variant="secondary">OTP · Magic links · Free · No signup</Badge>
@@ -116,16 +100,7 @@ export default function Otp() {
 
         <section id="how" className="scroll-mt-16 pt-16 sm:pt-20">
           <h2 className="text-2xl font-semibold tracking-tight">How it works</h2>
-          <ol className="mt-6 space-y-4">
-            {STEPS.map((step, i) => (
-              <li key={step} className="flex gap-4">
-                <span className="flex size-7 shrink-0 items-center justify-center rounded-full bg-muted font-mono text-xs font-medium">
-                  {i + 1}
-                </span>
-                <p className="pt-1 text-sm text-muted-foreground sm:text-base">{step}</p>
-              </li>
-            ))}
-          </ol>
+          <NumberedSteps items={STEPS} />
         </section>
 
         <section className="pt-16 sm:pt-20">
@@ -158,82 +133,14 @@ export default function Otp() {
           </p>
         </section>
 
-        <section className="pt-16 sm:pt-20">
-          <h2 className="text-2xl font-semibold tracking-tight">FAQ</h2>
-          <Card className="mt-6 gap-0 p-0">
-            <Accordion multiple={false} className="w-full">
-              {FAQ.map((item) => (
-                <AccordionItem key={item.q} value={item.q} className="px-5">
-                  <AccordionTrigger>{item.q}</AccordionTrigger>
-                  <AccordionContent className="text-muted-foreground">{item.a}</AccordionContent>
-                </AccordionItem>
-              ))}
-            </Accordion>
-          </Card>
-        </section>
+        <FaqSection items={FAQ} />
 
-        <section className="pt-16 pb-8 sm:pt-20">
-          <Card className="flex flex-col items-center gap-4 p-8 text-center">
-            <h2 className="text-xl font-semibold tracking-tight">Never wait on a code again.</h2>
-            <p className="max-w-md text-sm text-muted-foreground">
-              Open a disposable inbox and start receiving verification codes in seconds.
-            </p>
-            <div className="flex flex-wrap justify-center gap-3">
-              <Button render={<Link to="/" />}>Open smails</Button>
-              <Button
-                variant="outline"
-                render={
-                  <a href={GITHUB_URL} target="_blank" rel="noreferrer">
-                    GitHub
-                    <ArrowUpRight />
-                  </a>
-                }
-              />
-            </div>
-          </Card>
-        </section>
+        <CtaSection title="Never wait on a code again.">
+          Open a disposable inbox and start receiving verification codes in seconds.
+        </CtaSection>
       </main>
 
       <SiteFooter />
     </div>
   );
 }
-
-function StructuredData() {
-  const data = {
-    "@context": "https://schema.org",
-    "@graph": [
-      {
-        "@type": "HowTo",
-        name: "Get a verification code or OTP from email with a disposable inbox",
-        description:
-          "Use a free disposable inbox to receive an OTP, verification code, or magic link and read it from the web, CLI, REST API, or an MCP server.",
-        step: STEPS.map((s, i) => ({ "@type": "HowToStep", position: i + 1, text: s })),
-      },
-      {
-        "@type": "FAQPage",
-        mainEntity: FAQ.map((item) => ({
-          "@type": "Question",
-          name: item.q,
-          acceptedAnswer: { "@type": "Answer", text: item.a },
-        })),
-      },
-      {
-        "@type": "BreadcrumbList",
-        itemListElement: [
-          { "@type": "ListItem", position: 1, name: "smails", item: "https://smails.dev/" },
-          {
-            "@type": "ListItem",
-            position: 2,
-            name: "Verification codes",
-            item: "https://smails.dev/otp",
-          },
-        ],
-      },
-    ],
-  };
-  return (
-    // biome-ignore lint/security/noDangerouslySetInnerHtml: trusted JSON-LD built from static data
-    <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }} />
-  );
-}
diff --git a/worker/src/index.ts b/worker/src/index.ts
index 0b10905..d74d79a 100644
--- a/worker/src/index.ts
+++ b/worker/src/index.ts
@@ -1,12 +1,19 @@
 import { randomName } from "@scaleway/random-name";
 import { Hono } from "hono";
 import PostalMime from "postal-mime";
-import { AppError, Mailbox } from "./mailbox";
+import { httpStatusForError, Mailbox } from "./mailbox";
 
 export { Mailbox };
 
 const app = new Hono<{ Bindings: Env }>();
 
+// Tag every API response with the current deploy id so the frontend can detect
+// when the backend has been updated and prompt the user to refresh.
+app.use(async (c, next) => {
+  await next();
+  c.header("X-Smails-Version", c.env.CF_VERSION.id);
+});
+
 function generateAddress(): string {
   const name = randomName();
   const bytes = new Uint8Array(3);
@@ -61,7 +68,7 @@ app.post("/api/mailbox", async (c) => {
   const secret = generateSecret();
   const token = `${address}.${secret}`;
   const stub = c.env.MAILBOX.getByName(address);
-  const result = await stub.init(token, domain);
+  const result = await stub.create(token, domain);
   return c.json(result, 201);
 });
 
@@ -111,8 +118,9 @@ authed.delete("/messages/:id", async (c) => {
 app.route("/api/mailbox", authed);
 
 app.onError((err, c) => {
-  if (err instanceof AppError) {
-    return c.json({ error: err.message }, err.status as 400);
+  const status = httpStatusForError(err);
+  if (status !== null) {
+    return c.json({ error: err.message }, status as 400);
   }
   return c.json({ error: "Internal error" }, 500);
 });
@@ -121,8 +129,10 @@ export default {
   fetch: app.fetch,
 
   async email(message: ForwardableEmailMessage, env: Env): Promise<void> {
-    if (message.rawSize > 2 * 1024 * 1024) {
-      message.setReject("Message too large (max 2MB)");
+    // Stored base64 inflates the raw by ~4/3; bounce anything that wouldn't fit
+    // under the ~2 MB Durable Object SQLite row limit.
+    if (message.rawSize > 1.4 * 1024 * 1024) {
+      message.setReject("Message too large (max 1.4MB)");
       return;
     }
 
@@ -131,14 +141,29 @@ export default {
 
     const rawBytes = new Uint8Array(await new Response(message.raw).arrayBuffer());
     const raw = toBase64(rawBytes);
-    const parsed = await PostalMime.parse(rawBytes);
-
-    await stub.receiveEmail(
-      message.from,
-      parsed.from?.name || message.from,
-      parsed.subject || "(no subject)",
-      (parsed.text || "").substring(0, 200).replace(/\n/g, " "),
-      raw,
-    );
+
+    // Parse for display fields; if the MIME is malformed, fall back to
+    // placeholders so the message is still retained rather than bounced.
+    let fromName = message.from;
+    let subject = "(no subject)";
+    let preview = "";
+    try {
+      const parsed = await PostalMime.parse(rawBytes);
+      fromName = parsed.from?.name || message.from;
+      subject = parsed.subject || "(no subject)";
+      preview = (parsed.text || "").substring(0, 200).replace(/\n/g, " ");
+    } catch {
+      // keep placeholders; the raw message is still stored
+    }
+
+    try {
+      await stub.receiveMessage(message.from, fromName, subject, preview, raw);
+    } catch (err) {
+      // Storing failed (transient DO error, or the row exceeded SQLite limits).
+      // Don't silently accept — surface it so Email Routing reports the failure
+      // and the sender retries, instead of the message being lost without a trace.
+      console.error("receiveMessage failed", err);
+      throw err;
+    }
   },
 } satisfies ExportedHandler<Env>;
diff --git a/worker/src/mailbox.ts b/worker/src/mailbox.ts
index 72d3a18..c2b4e9d 100644
--- a/worker/src/mailbox.ts
+++ b/worker/src/mailbox.ts
@@ -2,6 +2,7 @@ import { DurableObject } from "cloudflare:workers";
 import PostalMime from "postal-mime";
 
 const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
 
 type Row = Record<string, SqlStorageValue>;
 
@@ -14,6 +15,22 @@ export class AppError extends Error {
   }
 }
 
+// An AppError thrown inside the Durable Object is flattened to a plain Error when
+// it crosses the RPC boundary: the subclass identity and the `status` own-property
+// are both dropped — only `message` survives. Map the known messages back to a
+// status so the Worker returns the real code instead of a blanket 500.
+const STATUS_BY_MESSAGE: Record<string, number> = {
+  Unauthorized: 401,
+  "Mailbox already exists": 409,
+  "Message not found": 404,
+};
+
+export function httpStatusForError(err: unknown): number | null {
+  if (err instanceof AppError) return err.status;
+  if (err instanceof Error) return STATUS_BY_MESSAGE[err.message] ?? null;
+  return null;
+}
+
 export class Mailbox extends DurableObject<Env> {
   private token: string = "";
 
@@ -58,12 +75,11 @@ export class Mailbox extends DurableObject<Env> {
     await this.ctx.storage.setAlarm(Date.now() + SEVEN_DAYS_MS);
   }
 
-  async init(token: string, domain: string): Promise<{ address: string; token: string }> {
+  async create(token: string, domain: string): Promise<{ address: string; token: string }> {
     if (this.token) {
       throw new AppError(409, "Mailbox already exists");
     }
     await this.ctx.storage.put("token", token);
-    await this.ctx.storage.put("domain", domain);
     this.token = token;
     await this.touchActivity();
     return { address: `${this.address}@${domain}`, token };
@@ -91,7 +107,17 @@ export class Mailbox extends DurableObject<Env> {
     }
     const row = rows[0];
     const rawBytes = Uint8Array.from(atob(row.raw as string), (c) => c.charCodeAt(0));
-    const parsed = await PostalMime.parse(rawBytes);
+    let html: string | null = null;
+    let text: string | null = null;
+    let attachments: unknown[] = [];
+    try {
+      const parsed = await PostalMime.parse(rawBytes);
+      html = parsed.html || null;
+      text = parsed.text || null;
+      attachments = parsed.attachments;
+    } catch {
+      // unparseable stored message — return metadata with an empty body
+    }
     return {
       id: row.id,
       from_addr: row.from_addr,
@@ -99,9 +125,9 @@ export class Mailbox extends DurableObject<Env> {
       subject: row.subject,
       received_at: row.received_at,
       read: row.read,
-      html: parsed.html || null,
-      text: parsed.text || null,
-      attachments: parsed.attachments,
+      html,
+      text,
+      attachments,
     };
   }
 
@@ -111,13 +137,17 @@ export class Mailbox extends DurableObject<Env> {
     this.ctx.storage.sql.exec("DELETE FROM messages WHERE id = ?", id);
   }
 
-  async receiveEmail(
+  async receiveMessage(
     fromAddr: string,
     fromName: string,
     subject: string,
     preview: string,
     raw: string,
   ): Promise<void> {
+    // Renew the expiry on any inbound mail. For an uninitialized mailbox this
+    // also arms the alarm so an orphaned DO (mail to an unknown address) is
+    // reclaimed in 7 days instead of lingering forever.
+    await this.touchActivity();
     if (!this.token) return;
     const id = crypto.randomUUID();
     this.ctx.storage.sql.exec(
@@ -130,7 +160,7 @@ export class Mailbox extends DurableObject<Env> {
       raw,
       Date.now(),
     );
-    this.broadcastNewEmail(id);
+    this.broadcastNewMessage(id);
   }
 
   async fetch(request: Request): Promise<Response> {
@@ -150,9 +180,16 @@ export class Mailbox extends DurableObject<Env> {
     return new Response(null, { status: 101, webSocket: client });
   }
 
-  webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): void {
+  async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
     if (message === "ping") {
       ws.send("pong");
+      // A live, pinging connection counts as activity — renew the expiry. Pings
+      // arrive every ~30s, so only re-arm once the alarm has drifted more than a
+      // day from full to avoid a storage write on every ping.
+      const current = await this.ctx.storage.getAlarm();
+      if (current === null || current - Date.now() < SEVEN_DAYS_MS - ONE_DAY_MS) {
+        await this.touchActivity();
+      }
     }
   }
 
@@ -160,8 +197,8 @@ export class Mailbox extends DurableObject<Env> {
     ws.close();
   }
 
-  private broadcastNewEmail(id: string): void {
-    const msg = JSON.stringify({ type: "new_email", id });
+  private broadcastNewMessage(id: string): void {
+    const msg = JSON.stringify({ type: "new_message", id });
     for (const ws of this.ctx.getWebSockets()) {
       ws.send(msg);
     }
diff --git a/worker/worker-configuration.d.ts b/worker/worker-configuration.d.ts
index 2e9a6de..bd2eaac 100644
--- a/worker/worker-configuration.d.ts
+++ b/worker/worker-configuration.d.ts
@@ -1,7 +1,8 @@
 /* eslint-disable */
-// Generated by Wrangler by running `wrangler types` (hash: c97fce2661f1121532c5d8800906f8f8)
+// Generated by Wrangler by running `wrangler types` (hash: 09f8164ac5caf5c41ccc8c6e8f927096)
 // Runtime types generated with workerd@1.20260623.1 2026-06-24 nodejs_compat
 interface __BaseEnv_Env {
+	CF_VERSION: WorkerVersionMetadata;
 	DOMAINS: "smails.dev";
 	MAILBOX: DurableObjectNamespace<import("./src/index").Mailbox>;
 }
diff --git a/worker/wrangler.jsonc b/worker/wrangler.jsonc
index bf13c42..f9a37c1 100644
--- a/worker/wrangler.jsonc
+++ b/worker/wrangler.jsonc
@@ -17,6 +17,9 @@
   "vars": {
     "DOMAINS": "smails.dev"
   },
+  "version_metadata": {
+    "binding": "CF_VERSION"
+  },
   "durable_objects": {
     "bindings": [
       {