@mailslot/core 0.0.1

package/README.md

@@ -0,0 +1,9 @@
+# @mailslot/core
+
+The Mailslot worker: self-hosted email inbox for AI agents on your own
+Cloudflare account. One Durable Object per address, MCP + HTTP + webhook
+surfaces, read-once OTP extraction.
+
+This package is deployed from source with wrangler — see the
+[setup guide](https://github.com/mailslot/mailslot#quick-start). For the
+guided deploy (coming soon): `npx create-mailslot`.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@mailslot/core",
+  "version": "0.0.1",
+  "description": "Self-hosted email inbox for AI agents, on your own Cloudflare account",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "wrangler.jsonc",
+    "README.md"
+  ],
+  "homepage": "https://mailslot.dev",
+  "keywords": [
+    "ai-agents",
+    "email",
+    "mcp",
+    "cloudflare-workers",
+    "durable-objects",
+    "self-hosted"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mailslot/mailslot.git"
+  },
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "cf-typegen": "wrangler types"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.23.0",
+    "agents": "^0.2.0",
+    "postal-mime": "^2.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "wrangler": "^4.0.0"
+  }
+}

package/src/api.ts

@@ -0,0 +1,96 @@
+import { getAgentByName } from "agents";
+import type { Env } from "./env";
+import { mintLocalPart } from "./auth";
+
+/**
+ * Plain HTTP surface mirroring the MCP tools.
+ *
+ *   POST /v1/addresses                                  {prefix?}
+ *   GET  /v1/inboxes/:address/messages                  ?q&from_contains&subject_contains&limit
+ *   GET  /v1/inboxes/:address/messages/:id
+ *   POST /v1/inboxes/:address/extract-otp               {message_id?}
+ *   POST /v1/inboxes/:address/extract-links             {message_id?}
+ *   GET  /v1/inboxes/:address/wait                      ?timeout_s&since_s&from_contains&subject_contains
+ */
+export async function handleApi(request: Request, env: Env): Promise<Response> {
+  const url = new URL(request.url);
+  const parts = url.pathname.split("/").filter(Boolean); // ["v1", ...]
+
+  try {
+    if (parts[1] === "addresses" && request.method === "POST") {
+      if (!env.EMAIL_DOMAIN) {
+        return Response.json({ error: "EMAIL_DOMAIN is not configured" }, { status: 500 });
+      }
+      const body = await readJson(request);
+      const address = `${mintLocalPart(body.prefix)}@${env.EMAIL_DOMAIN.toLowerCase()}`;
+      return Response.json({ address }, { status: 201 });
+    }
+
+    if (parts[1] === "inboxes" && parts[2]) {
+      const address = decodeURIComponent(parts[2]).toLowerCase();
+      if (!address.includes("@")) {
+        return Response.json({ error: "address must be a full email address" }, { status: 400 });
+      }
+      const inbox = await getAgentByName(env.Inbox, address);
+      const rest = parts.slice(3);
+
+      if (rest[0] === "messages" && !rest[1] && request.method === "GET") {
+        const messages = await inbox.list({
+          q: url.searchParams.get("q") ?? undefined,
+          fromContains: url.searchParams.get("from_contains") ?? undefined,
+          subjectContains: url.searchParams.get("subject_contains") ?? undefined,
+          limit: numParam(url, "limit")
+        });
+        return Response.json({ messages });
+      }
+
+      if (rest[0] === "messages" && rest[1] && request.method === "GET") {
+        const message = await inbox.get(rest[1]);
+        return message
+          ? Response.json({ message })
+          : Response.json({ error: "message not found" }, { status: 404 });
+      }
+
+      if (rest[0] === "extract-otp" && request.method === "POST") {
+        const body = await readJson(request);
+        return Response.json(await inbox.extractOtp(body.message_id));
+      }
+
+      if (rest[0] === "extract-links" && request.method === "POST") {
+        const body = await readJson(request);
+        return Response.json(await inbox.extractLinks(body.message_id));
+      }
+
+      if (rest[0] === "wait" && request.method === "GET") {
+        const message = await inbox.waitForMessage({
+          timeoutMs: (numParam(url, "timeout_s") ?? 60) * 1000,
+          sinceSecondsAgo: numParam(url, "since_s"),
+          fromContains: url.searchParams.get("from_contains") ?? undefined,
+          subjectContains: url.searchParams.get("subject_contains") ?? undefined
+        });
+        return Response.json({ message }); // message: null on timeout
+      }
+    }
+
+    return Response.json({ error: "not found" }, { status: 404 });
+  } catch (e) {
+    console.error("api error:", e);
+    return Response.json({ error: "internal error" }, { status: 500 });
+  }
+}
+
+async function readJson(request: Request): Promise<Record<string, string | undefined>> {
+  try {
+    const body = await request.json();
+    return typeof body === "object" && body !== null ? (body as Record<string, string>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function numParam(url: URL, name: string): number | undefined {
+  const value = url.searchParams.get(name);
+  if (value === null) return undefined;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : undefined;
+}

package/src/auth.ts

@@ -0,0 +1,31 @@
+/** Constant-time bearer token check (compares SHA-256 digests). */
+export async function checkBearerToken(request: Request, expected: string | undefined): Promise<boolean> {
+  if (!expected) return false; // unset token = locked, never open
+  const header = request.headers.get("authorization") ?? "";
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  if (!match) return false;
+
+  const enc = new TextEncoder();
+  const [a, b] = await Promise.all([
+    crypto.subtle.digest("SHA-256", enc.encode(match[1])),
+    crypto.subtle.digest("SHA-256", enc.encode(expected))
+  ]);
+  return timingSafeEqual(new Uint8Array(a), new Uint8Array(b));
+}
+
+function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+
+/** Mint a random address local part: prefix-x7k2f9 (lowercase, unambiguous). */
+export function mintLocalPart(prefix?: string): string {
+  const safePrefix = (prefix ?? "agent").toLowerCase().replace(/[^a-z0-9-]/g, "").slice(0, 20) || "agent";
+  const alphabet = "abcdefghjkmnpqrstuvwxyz23456789"; // no 0/o/1/l/i
+  const bytes = crypto.getRandomValues(new Uint8Array(6));
+  let suffix = "";
+  for (const byte of bytes) suffix += alphabet[byte % alphabet.length];
+  return `${safePrefix}-${suffix}`;
+}

package/src/env.ts

@@ -0,0 +1,25 @@
+import type { Inbox } from "./inbox";
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      Inbox: DurableObjectNamespace<Inbox>;
+      MailslotMcp: DurableObjectNamespace;
+      RAW: R2Bucket;
+      /** Bearer token for the HTTP API and MCP endpoint (secret). */
+      MAILSLOT_TOKEN: string;
+      /** Domain receiving agent mail, e.g. agents.example.com. */
+      EMAIL_DOMAIN?: string;
+      /** Verified Email Routing destination to forward copies to. */
+      FORWARD_TO?: string;
+      /** "all" forwards every inbound message to FORWARD_TO; default "none". */
+      FORWARD_MODE?: string;
+      /** URL receiving message.received webhook events. */
+      WEBHOOK_URL?: string;
+      /** If set, webhook payloads are HMAC-SHA256 signed (X-Mailslot-Signature). */
+      WEBHOOK_SECRET?: string;
+    }
+  }
+}
+
+export type Env = Cloudflare.Env;

package/src/extract.ts

@@ -0,0 +1,98 @@
+/**
+ * Pure extraction helpers. No I/O — unit-tested directly.
+ */
+
+const OTP_KEYWORDS =
+  /\b(otp|one[- ]?time|verification|verify|confirm(?:ation)?|security|login|sign[- ]?in|access|auth(?:entication)?|pass)\b|code|코드|認証|驗證|验证|kod/i;
+
+/** Strip HTML to text, crudely but safely (no DOM on Workers). */
+export function htmlToText(html: string): string {
+  return html
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n)))
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+type OtpCandidate = { code: string; score: number };
+
+/**
+ * Find the most likely OTP in a message.
+ * Heuristics: 4-8 digit (or dash/space-grouped) runs, scored by proximity to
+ * OTP-ish keywords and penalized when they look like dates, phones, or prices.
+ */
+export function extractOtp(subject: string, body: string): string | null {
+  const haystacks = [
+    { text: subject ?? "", bonus: 2 },
+    { text: body ?? "", bonus: 0 }
+  ];
+  const candidates: OtpCandidate[] = [];
+
+  for (const { text, bonus } of haystacks) {
+    // 123456 | 123-456 | 123 456 | A1B2C3-style codes
+    // Trailing sentence punctuation is fine; reject only digit/decimal continuations.
+    const re = /(?<![\d.,-])(\d{4,8}|\d{3}[- ]\d{3}|[A-Z0-9]{6,8})(?!\d|[.,]\d)/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(text)) !== null) {
+      const raw = m[1];
+      const code = raw.replace(/[- ]/g, "");
+      // Alphanumeric candidates must mix letters and digits (else it's a word)
+      if (/[A-Z]/.test(code) && !/\d/.test(code)) continue;
+      // All-digit length sanity
+      if (/^\d+$/.test(code) && (code.length < 4 || code.length > 8)) continue;
+
+      let score = bonus;
+      const ctx = text.slice(Math.max(0, m.index - 60), m.index + raw.length + 60);
+      if (OTP_KEYWORDS.test(ctx)) score += 4;
+      // Penalties: looks like a year, a date fragment, a price, or a phone
+      if (/^(19|20)\d{2}$/.test(code)) score -= 3;
+      if (/[$€£¥]\s*$/.test(text.slice(Math.max(0, m.index - 4), m.index))) score -= 3;
+      if (/\d[\d\s().-]{8,}/.test(text.slice(Math.max(0, m.index - 12), m.index + raw.length + 4))) score -= 2;
+      // 6 digits is the archetypal OTP
+      if (/^\d{6}$/.test(code)) score += 2;
+
+      candidates.push({ code, score });
+    }
+  }
+
+  candidates.sort((a, b) => b.score - a.score);
+  const best = candidates[0];
+  return best && best.score >= 2 ? best.code : null;
+}
+
+/** Extract unique http(s) links, hrefs first (HTML), then bare URLs (text). */
+export function extractLinks(text: string, html: string): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  const push = (u: string) => {
+    const cleaned = u.replace(/[)\].,;'"!>]+$/, "");
+    if (!seen.has(cleaned)) {
+      seen.add(cleaned);
+      out.push(cleaned);
+    }
+  };
+
+  if (html) {
+    const hrefRe = /href\s*=\s*["']?(https?:\/\/[^"'\s>]+)/gi;
+    let m: RegExpExecArray | null;
+    while ((m = hrefRe.exec(html)) !== null) push(m[1]);
+  }
+  if (text) {
+    const urlRe = /https?:\/\/[^\s<>"']+/gi;
+    let m: RegExpExecArray | null;
+    while ((m = urlRe.exec(text)) !== null) push(m[0]);
+  }
+  return out;
+}
+
+/** First ~140 chars of body text for list views and webhook payloads. */
+export function makeSnippet(text: string, html: string): string {
+  const source = (text && text.trim()) || htmlToText(html || "");
+  return source.replace(/\s+/g, " ").trim().slice(0, 140);
+}

package/src/inbox.ts

@@ -0,0 +1,287 @@
+import { Agent } from "agents";
+import PostalMime from "postal-mime";
+import type { Env } from "./env";
+import { extractLinks, extractOtp, htmlToText, makeSnippet } from "./extract";
+
+/** Shape of the AgentEmail proxy passed by routeAgentEmail (agents SDK). */
+type AgentEmail = {
+  from: string;
+  to: string;
+  headers: Headers;
+  rawSize: number;
+  getRaw: () => Promise<Uint8Array>;
+  setReject: (reason: string) => void;
+  forward: (rcptTo: string, headers?: Headers) => Promise<void>;
+};
+
+export type MessageSummary = {
+  id: string;
+  from: string;
+  subject: string;
+  snippet: string;
+  receivedAt: number;
+  consumed: boolean;
+};
+
+export type MessageDetail = MessageSummary & {
+  text: string;
+  html: string;
+  rawKey: string;
+};
+
+type MessageRow = {
+  id: string;
+  from_addr: string;
+  subject: string;
+  snippet: string;
+  text_body: string;
+  html_body: string;
+  raw_key: string;
+  received_at: number;
+  consumed_at: number | null;
+};
+
+export type ListOptions = {
+  limit?: number;
+  q?: string;
+  fromContains?: string;
+  subjectContains?: string;
+};
+
+export type WaitOptions = {
+  timeoutMs?: number;
+  /** Only match messages received in the last N seconds (default 60) or later. */
+  sinceSecondsAgo?: number;
+  fromContains?: string;
+  subjectContains?: string;
+};
+
+const MAX_WAIT_MS = 120_000;
+const WAIT_POLL_MS = 1_000;
+const WEBHOOK_MAX_ATTEMPTS = 3;
+
+/**
+ * One Durable Object per email address. Instance name = lowercased address.
+ * Receives mail via routeAgentEmail → onEmail, exposes read tools over RPC.
+ */
+export class Inbox extends Agent<Env> {
+  onStart() {
+    this.sql`
+      CREATE TABLE IF NOT EXISTS messages (
+        id TEXT PRIMARY KEY,
+        from_addr TEXT NOT NULL,
+        subject TEXT NOT NULL DEFAULT '',
+        snippet TEXT NOT NULL DEFAULT '',
+        text_body TEXT NOT NULL DEFAULT '',
+        html_body TEXT NOT NULL DEFAULT '',
+        raw_key TEXT NOT NULL,
+        received_at INTEGER NOT NULL,
+        consumed_at INTEGER
+      )
+    `;
+    this.sql`CREATE INDEX IF NOT EXISTS idx_messages_received ON messages (received_at DESC)`;
+  }
+
+  /** The address this inbox serves (the DO instance name). */
+  get address(): string {
+    return this.name;
+  }
+
+  async onEmail(email: AgentEmail) {
+    const raw = await email.getRaw();
+    const parsed = await PostalMime.parse(raw);
+
+    const id = crypto.randomUUID();
+    const receivedAt = Date.now();
+    const subject = parsed.subject ?? "";
+    const text = parsed.text ?? "";
+    const html = parsed.html ?? "";
+    const snippet = makeSnippet(text, html);
+    const rawKey = `raw/${this.address}/${id}.eml`;
+
+    await this.env.RAW.put(rawKey, raw);
+    this.sql`
+      INSERT INTO messages (id, from_addr, subject, snippet, text_body, html_body, raw_key, received_at)
+      VALUES (${id}, ${email.from}, ${subject}, ${snippet}, ${text}, ${html}, ${rawKey}, ${receivedAt})
+    `;
+
+    // Forward decision must happen here: the email proxy is only valid
+    // during this invocation.
+    if (this.env.FORWARD_MODE === "all" && this.env.FORWARD_TO) {
+      try {
+        await email.forward(this.env.FORWARD_TO);
+      } catch (e) {
+        console.error(`forward to ${this.env.FORWARD_TO} failed:`, e);
+      }
+    }
+
+    if (this.env.WEBHOOK_URL) {
+      await this.deliverWebhook({
+        v: 1,
+        event: "message.received",
+        inbox: this.address,
+        message: {
+          id,
+          from: email.from,
+          subject,
+          snippet,
+          receivedAt
+        }
+      });
+    }
+  }
+
+  list(opts: ListOptions = {}): MessageSummary[] {
+    const limit = Math.min(Math.max(opts.limit ?? 20, 1), 100);
+    // Small per-address volumes: fetch recent window, filter in JS.
+    const rows = this.sql<MessageRow>`
+      SELECT * FROM messages ORDER BY received_at DESC LIMIT 200
+    `;
+    const match = (row: MessageRow) => {
+      const q = opts.q?.toLowerCase();
+      if (
+        q &&
+        !row.subject.toLowerCase().includes(q) &&
+        !row.from_addr.toLowerCase().includes(q) &&
+        !row.text_body.toLowerCase().includes(q)
+      )
+        return false;
+      if (opts.fromContains && !row.from_addr.toLowerCase().includes(opts.fromContains.toLowerCase()))
+        return false;
+      if (opts.subjectContains && !row.subject.toLowerCase().includes(opts.subjectContains.toLowerCase()))
+        return false;
+      return true;
+    };
+    return rows.filter(match).slice(0, limit).map(toSummary);
+  }
+
+  get(id: string): MessageDetail | null {
+    const rows = this.sql<MessageRow>`SELECT * FROM messages WHERE id = ${id}`;
+    const row = rows[0];
+    return row ? toDetail(row) : null;
+  }
+
+  /**
+   * Extract an OTP. Read-once: succeeds at most once per message.
+   * Without messageId, uses the newest unconsumed message.
+   */
+  extractOtp(messageId?: string): { otp: string | null; messageId: string | null; error?: string } {
+    const row = messageId
+      ? this.sql<MessageRow>`SELECT * FROM messages WHERE id = ${messageId}`[0]
+      : this.sql<MessageRow>`
+          SELECT * FROM messages WHERE consumed_at IS NULL ORDER BY received_at DESC LIMIT 1
+        `[0];
+
+    if (!row) {
+      return { otp: null, messageId: messageId ?? null, error: messageId ? "message not found" : "no unconsumed messages" };
+    }
+    if (row.consumed_at !== null) {
+      return { otp: null, messageId: row.id, error: "already consumed (read-once)" };
+    }
+
+    const body = row.text_body || htmlToText(row.html_body);
+    const otp = extractOtp(row.subject, body);
+    if (!otp) {
+      return { otp: null, messageId: row.id, error: "no OTP-like code found" };
+    }
+
+    this.sql`UPDATE messages SET consumed_at = ${Date.now()} WHERE id = ${row.id}`;
+    return { otp, messageId: row.id };
+  }
+
+  extractLinks(messageId?: string): { links: string[]; messageId: string | null; error?: string } {
+    const row = messageId
+      ? this.sql<MessageRow>`SELECT * FROM messages WHERE id = ${messageId}`[0]
+      : this.sql<MessageRow>`SELECT * FROM messages ORDER BY received_at DESC LIMIT 1`[0];
+    if (!row) {
+      return { links: [], messageId: messageId ?? null, error: messageId ? "message not found" : "inbox is empty" };
+    }
+    return { links: extractLinks(row.text_body, row.html_body), messageId: row.id };
+  }
+
+  /** Long-poll for a matching message. Returns null on timeout. */
+  async waitForMessage(opts: WaitOptions = {}): Promise<MessageSummary | null> {
+    const timeoutMs = Math.min(Math.max(opts.timeoutMs ?? 60_000, 1_000), MAX_WAIT_MS);
+    const sinceTs = Date.now() - (opts.sinceSecondsAgo ?? 60) * 1000;
+    const deadline = Date.now() + timeoutMs;
+
+    while (true) {
+      const rows = this.sql<MessageRow>`
+        SELECT * FROM messages WHERE received_at >= ${sinceTs} ORDER BY received_at DESC LIMIT 50
+      `;
+      const hit = rows.find((row) => {
+        if (opts.fromContains && !row.from_addr.toLowerCase().includes(opts.fromContains.toLowerCase()))
+          return false;
+        if (opts.subjectContains && !row.subject.toLowerCase().includes(opts.subjectContains.toLowerCase()))
+          return false;
+        return true;
+      });
+      if (hit) return toSummary(hit);
+      if (Date.now() + WAIT_POLL_MS > deadline) return null;
+      await new Promise((r) => setTimeout(r, WAIT_POLL_MS));
+    }
+  }
+
+  info(): { address: string; messageCount: number } {
+    const rows = this.sql<{ n: number }>`SELECT COUNT(*) AS n FROM messages`;
+    return { address: this.address, messageCount: rows[0]?.n ?? 0 };
+  }
+
+  // --- webhook delivery -----------------------------------------------------
+
+  private async deliverWebhook(payload: Record<string, unknown>, attempt = 1) {
+    const url = this.env.WEBHOOK_URL;
+    if (!url) return;
+    const body = JSON.stringify(payload);
+    try {
+      const headers: Record<string, string> = { "content-type": "application/json" };
+      if (this.env.WEBHOOK_SECRET) {
+        headers["x-mailslot-signature"] = await hmacHex(this.env.WEBHOOK_SECRET, body);
+      }
+      const res = await fetch(url, { method: "POST", headers, body });
+      if (!res.ok) throw new Error(`webhook responded ${res.status}`);
+    } catch (e) {
+      console.error(`webhook attempt ${attempt} failed:`, e);
+      if (attempt < WEBHOOK_MAX_ATTEMPTS) {
+        await this.schedule(30 * attempt, "retryWebhook", { payload, attempt: attempt + 1 });
+      }
+    }
+  }
+
+  /** Scheduled-task callback for webhook retries (must be public for schedule()). */
+  async retryWebhook(data: { payload: Record<string, unknown>; attempt: number }) {
+    await this.deliverWebhook(data.payload, data.attempt);
+  }
+}
+
+function toSummary(row: MessageRow): MessageSummary {
+  return {
+    id: row.id,
+    from: row.from_addr,
+    subject: row.subject,
+    snippet: row.snippet,
+    receivedAt: row.received_at,
+    consumed: row.consumed_at !== null
+  };
+}
+
+function toDetail(row: MessageRow): MessageDetail {
+  return {
+    ...toSummary(row),
+    text: row.text_body,
+    html: row.html_body,
+    rawKey: row.raw_key
+  };
+}
+
+async function hmacHex(secret: string, body: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body));
+  return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+import { routeAgentEmail } from "agents";
+import type { Env } from "./env";
+import { Inbox } from "./inbox";
+import { MailslotMcp } from "./mcp";
+import { handleApi } from "./api";
+import { checkBearerToken } from "./auth";
+
+export { Inbox, MailslotMcp };
+
+const mcpHandler = MailslotMcp.serve("/mcp", { binding: "MailslotMcp" });
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === "/v1/health") {
+      return Response.json({ ok: true, service: "mailslot" });
+    }
+
+    const authorized = await checkBearerToken(request, env.MAILSLOT_TOKEN);
+    if (!authorized) {
+      return Response.json({ error: "unauthorized" }, { status: 401 });
+    }
+
+    if (url.pathname === "/mcp" || url.pathname.startsWith("/mcp/")) {
+      return mcpHandler.fetch(request, env, ctx);
+    }
+    if (url.pathname.startsWith("/v1/")) {
+      return handleApi(request, env);
+    }
+    return Response.json({ error: "not found" }, { status: 404 });
+  },
+
+  async email(message: ForwardableEmailMessage, env: Env) {
+    await routeAgentEmail(message, env, {
+      // Catch-all: every address on the domain gets its own Inbox DO,
+      // named by the full lowercased recipient address.
+      resolver: async (email: ForwardableEmailMessage) => {
+        const to = email.to?.toLowerCase();
+        if (!to || !isAcceptableAddress(to, env.EMAIL_DOMAIN)) {
+          email.setReject("Unknown recipient");
+          return null;
+        }
+        return { agentName: "Inbox", agentId: to };
+      }
+    });
+  }
+} satisfies ExportedHandler<Env>;
+
+function isAcceptableAddress(to: string, domain?: string): boolean {
+  const at = to.lastIndexOf("@");
+  if (at < 1) return false;
+  const local = to.slice(0, at);
+  if (local.length > 64) return false;
+  // If EMAIL_DOMAIN is configured, only accept mail for that domain.
+  if (domain && to.slice(at + 1) !== domain.toLowerCase()) return false;
+  return true;
+}

package/src/mcp.ts

@@ -0,0 +1,125 @@
+import { getAgentByName } from "agents";
+import { McpAgent } from "agents/mcp";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { Env } from "./env";
+import { mintLocalPart } from "./auth";
+
+const ADDRESS = z.string().email().describe("Full inbox address, e.g. agent-x7k2f9@agents.example.com");
+
+/**
+ * MCP surface. Tools are thin wrappers over Inbox DO RPC — the same engine
+ * the HTTP API uses. One stateless server; inbox state lives in Inbox DOs.
+ */
+export class MailslotMcp extends McpAgent<Env> {
+  server = new McpServer({ name: "mailslot", version: "0.0.1" });
+
+  async init() {
+    const env = this.env;
+
+    const inbox = (address: string) => getAgentByName(env.Inbox, address.toLowerCase());
+    const json = (value: unknown) => ({
+      content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }]
+    });
+
+    this.server.registerTool(
+      "create_address",
+      {
+        description:
+          "Mint a fresh, never-used email address for a task. Use one address per signup/task; do not reuse.",
+        inputSchema: {
+          prefix: z.string().optional().describe("Optional address prefix, e.g. 'signup' → signup-x7k2f9@…")
+        }
+      },
+      async ({ prefix }) => {
+        if (!env.EMAIL_DOMAIN) return json({ error: "EMAIL_DOMAIN is not configured on the server" });
+        return json({ address: `${mintLocalPart(prefix)}@${env.EMAIL_DOMAIN.toLowerCase()}` });
+      }
+    );
+
+    this.server.registerTool(
+      "list_messages",
+      {
+        description: "List recent messages in an inbox, newest first. Optional substring filters.",
+        inputSchema: {
+          address: ADDRESS,
+          q: z.string().optional().describe("Match in subject, sender, or body"),
+          from_contains: z.string().optional(),
+          subject_contains: z.string().optional(),
+          limit: z.number().int().min(1).max(100).optional()
+        }
+      },
+      async ({ address, q, from_contains, subject_contains, limit }) => {
+        const stub = await inbox(address);
+        return json(await stub.list({ q, fromContains: from_contains, subjectContains: subject_contains, limit }));
+      }
+    );
+
+    this.server.registerTool(
+      "get_message",
+      {
+        description: "Fetch a full message (text, HTML, headers reference) by id.",
+        inputSchema: { address: ADDRESS, message_id: z.string() }
+      },
+      async ({ address, message_id }) => {
+        const stub = await inbox(address);
+        const message = await stub.get(message_id);
+        return json(message ?? { error: "message not found" });
+      }
+    );
+
+    this.server.registerTool(
+      "extract_otp",
+      {
+        description:
+          "Extract the one-time code from a message. READ-ONCE: each message yields its OTP at most once. " +
+          "Omit message_id to use the newest unconsumed message.",
+        inputSchema: { address: ADDRESS, message_id: z.string().optional() }
+      },
+      async ({ address, message_id }) => {
+        const stub = await inbox(address);
+        return json(await stub.extractOtp(message_id));
+      }
+    );
+
+    this.server.registerTool(
+      "extract_links",
+      {
+        description:
+          "Extract links (verification/magic links first, by document order) from a message. " +
+          "Omit message_id to use the newest message.",
+        inputSchema: { address: ADDRESS, message_id: z.string().optional() }
+      },
+      async ({ address, message_id }) => {
+        const stub = await inbox(address);
+        return json(await stub.extractLinks(message_id));
+      }
+    );
+
+    this.server.registerTool(
+      "wait_for_message",
+      {
+        description:
+          "Block until a matching message arrives (long-poll), or timeout. Call right after triggering the email " +
+          "(signup, password reset). Returns the message summary, or null on timeout.",
+        inputSchema: {
+          address: ADDRESS,
+          timeout_s: z.number().int().min(1).max(120).optional().describe("Default 60"),
+          since_s: z.number().int().min(0).optional().describe("Also match messages up to N seconds old (default 60)"),
+          from_contains: z.string().optional(),
+          subject_contains: z.string().optional()
+        }
+      },
+      async ({ address, timeout_s, since_s, from_contains, subject_contains }) => {
+        const stub = await inbox(address);
+        const message = await stub.waitForMessage({
+          timeoutMs: (timeout_s ?? 60) * 1000,
+          sinceSecondsAgo: since_s,
+          fromContains: from_contains,
+          subjectContains: subject_contains
+        });
+        return json({ message });
+      }
+    );
+  }
+}

package/src/shims/ai.ts

@@ -0,0 +1,8 @@
+/**
+ * Stub for the optional "ai" (Vercel AI SDK) dependency that the agents SDK
+ * imports dynamically in code paths Mailslot never uses. Aliased in
+ * wrangler.jsonc so the bundler can resolve it without shipping the SDK.
+ */
+export function jsonSchema(): never {
+  throw new Error("The 'ai' package is not installed — this code path is unused by Mailslot.");
+}

package/wrangler.jsonc

@@ -0,0 +1,39 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "mailslot",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-04-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": {
+    "bindings": [
+      { "name": "Inbox", "class_name": "Inbox" },
+      { "name": "MailslotMcp", "class_name": "MailslotMcp" }
+    ]
+  },
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["Inbox", "MailslotMcp"] }
+  ],
+  "r2_buckets": [
+    { "binding": "RAW", "bucket_name": "mailslot-raw" }
+  ],
+  "vars": {
+    // "all" forwards every inbound message to FORWARD_TO (a verified destination); "none" disables
+    "FORWARD_MODE": "none"
+  },
+  // Instance-specific values are NOT in this file (it ships generic in the repo).
+  // Set once per instance; keep_vars makes them survive every deploy:
+  //   EMAIL_DOMAIN   — var, set in dashboard (Workers → mailslot → Settings → Variables)
+  //                    or first deploy: wrangler deploy --var EMAIL_DOMAIN:mail.example.com
+  //   MAILSLOT_TOKEN — secret: openssl rand -hex 24 | wrangler secret put MAILSLOT_TOKEN
+  // Optional dashboard vars: FORWARD_TO, WEBHOOK_URL; optional secret: WEBHOOK_SECRET
+  "keep_vars": true,
+  "alias": {
+    // Optional dep of the agents SDK, dynamically imported in paths we don't use
+    "ai": "./src/shims/ai.ts"
+  },
+  "observability": { "enabled": true }
+  // Secrets (set via `wrangler secret put`):
+  //   MAILSLOT_TOKEN  — bearer token for HTTP API + MCP
+  //   WEBHOOK_SECRET  — optional, HMAC-signs webhook payloads
+  // Optional vars: FORWARD_TO, WEBHOOK_URL
+}