Add project email (mailboxes) tools and CLI commands

New MCP tools: create_mailbox, send_email, list_emails, get_email
New CLI commands: run402 email {create, send, list, get}
New OpenClaw shim: openclaw/scripts/email.mjs

Supports project-scoped mailboxes at <slug>@mail.run402.com with
template-based sending (project_invite, magic_link, notification).
Mailbox ID stored in keystore for automatic lookup on subsequent commands.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: MajorTal

SKILL.md

@@ -241,6 +241,59 @@ Setting an existing key overwrites it. All project functions are automatically u
 set_secret(project_id: "prj_...", key: "STRIPE_SECRET_KEY", value: "sk_live_...")
 ```
 
+### create_mailbox
+
+Create a project-scoped email mailbox. One mailbox per project.
+
+**Parameters:**
+- `project_id` (required) — Project ID
+- `slug` (required) — Mailbox slug (3-63 chars, lowercase alphanumeric + hyphens, no consecutive hyphens). Creates `<slug>@mail.run402.com`.
+
+**Example:**
+```
+create_mailbox(project_id: "prj_...", slug: "my-app")
+```
+
+### send_email
+
+Send a template-based email from the project's mailbox. Single recipient only.
+
+**Parameters:**
+- `project_id` (required) — Project ID
+- `template` (required) — Template name: `project_invite`, `magic_link`, or `notification`
+- `to` (required) — Recipient email address
+- `variables` (required) — Template variables object. `project_invite`: `project_name`, `invite_url`. `magic_link`: `project_name`, `link_url`, `expires_in`. `notification`: `project_name`, `message` (max 500 chars).
+
+**Example:**
+```
+send_email(project_id: "prj_...", template: "project_invite", to: "user@example.com", variables: {"project_name": "My App", "invite_url": "https://..."})
+```
+
+### list_emails
+
+List sent emails from the project's mailbox.
+
+**Parameters:**
+- `project_id` (required) — Project ID
+
+**Example:**
+```
+list_emails(project_id: "prj_...")
+```
+
+### get_email
+
+Get a sent email with details and any replies.
+
+**Parameters:**
+- `project_id` (required) — Project ID
+- `message_id` (required) — Message ID to retrieve
+
+**Example:**
+```
+get_email(project_id: "prj_...", message_id: "msg_...")
+```
+
 ## Standard Workflow
 
 Follow this sequence to go from zero to a working database:

cli/cli.mjs

@@ -33,6 +33,7 @@ Commands:
   subdomains  Manage custom subdomains (claim, list, delete)
   apps        Browse and manage the app marketplace
   image       Generate AI images via x402 or MPP micropayments
+  email       Send template-based emails from your project
   message     Send messages to Run402 developers
   agent       Manage agent identity (contact info)
 
@@ -131,6 +132,11 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "email": {
+    const { run } = await import("./lib/email.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "message": {
     const { run } = await import("./lib/message.mjs");
     await run(sub, rest);

cli/lib/email.mjs

@@ -0,0 +1,206 @@
+import { findProject, resolveProjectId, API, updateProject, loadKeyStore, saveKeyStore } from "./config.mjs";
+
+const HELP = `run402 email — Send template-based emails from your project
+
+Usage:
+  run402 email <subcommand> [args...]
+
+Subcommands:
+  create <slug> [--project <id>]     Create a mailbox (<slug>@mail.run402.com)
+  send   --template <name> --to <email> [--var key=value ...] [--project <id>]
+                                     Send a template email
+  list   [--project <id>]            List sent emails
+  get    <message_id> [--project <id>]  Get a message with replies
+
+Templates:
+  project_invite  — requires --var project_name=... --var invite_url=...
+  magic_link      — requires --var project_name=... --var link_url=... --var expires_in=...
+  notification    — requires --var project_name=... --var message=... (max 500 chars)
+
+Examples:
+  run402 email create my-app
+  run402 email send --template project_invite --to user@example.com \\
+    --var project_name="My App" --var invite_url="https://example.com/invite/abc"
+  run402 email send --template notification --to admin@example.com \\
+    --var project_name="My App" --var message="Deploy complete"
+  run402 email list
+  run402 email get msg_abc123
+
+Notes:
+  - One mailbox per project
+  - Single recipient per send (no CC/BCC)
+  - Slug: 3-63 chars, lowercase alphanumeric + hyphens, no consecutive hyphens
+  - Rate limits vary by tier (prototype: 10/day, hobby: 50/day, team: 200/day)
+  - --project defaults to the active project
+`;
+
+const SLUG_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+function parseFlag(args, flag) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === flag && args[i + 1]) return args[i + 1];
+  }
+  return null;
+}
+
+function parseVars(args) {
+  const vars = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--var" && args[i + 1]) {
+      const raw = args[++i];
+      const eq = raw.indexOf("=");
+      if (eq > 0) {
+        vars[raw.slice(0, eq)] = raw.slice(eq + 1);
+      }
+    }
+  }
+  return vars;
+}
+
+async function resolveMailboxId(projectId, serviceKey) {
+  const store = loadKeyStore();
+  const proj = store.projects[projectId];
+  if (proj && proj.mailbox_id) return proj.mailbox_id;
+
+  // Fallback: discover via API
+  const res = await fetch(`${API}/mailboxes/v1`, {
+    headers: { "Authorization": `Bearer ${serviceKey}` },
+  });
+  if (!res.ok) {
+    const data = await res.json().catch(() => ({}));
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data }));
+    process.exit(1);
+  }
+  const mailboxes = await res.json();
+  if (!Array.isArray(mailboxes) || mailboxes.length === 0) {
+    console.error(JSON.stringify({ status: "error", message: "No mailbox found. Run: run402 email create <slug>" }));
+    process.exit(1);
+  }
+  const mb = mailboxes[0];
+  updateProject(projectId, { mailbox_id: mb.id, mailbox_address: mb.address });
+  return mb.id;
+}
+
+async function create(args) {
+  const slug = args.find(a => !a.startsWith("--"));
+  const projectId = resolveProjectId(parseFlag(args, "--project"));
+  const p = findProject(projectId);
+
+  if (!slug) {
+    console.error(JSON.stringify({ status: "error", message: "Missing slug. Usage: run402 email create <slug>" }));
+    process.exit(1);
+  }
+  if (slug.length < 3 || slug.length > 63) {
+    console.error(JSON.stringify({ status: "error", message: "Slug must be 3-63 characters." }));
+    process.exit(1);
+  }
+  if (!SLUG_RE.test(slug)) {
+    console.error(JSON.stringify({ status: "error", message: "Slug must be lowercase alphanumeric + hyphens, start/end with alphanumeric." }));
+    process.exit(1);
+  }
+  if (slug.includes("--")) {
+    console.error(JSON.stringify({ status: "error", message: "Slug must not contain consecutive hyphens." }));
+    process.exit(1);
+  }
+
+  const res = await fetch(`${API}/mailboxes/v1`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ slug, project_id: projectId }),
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data }));
+    process.exit(1);
+  }
+
+  updateProject(projectId, { mailbox_id: data.id, mailbox_address: data.address });
+  console.log(JSON.stringify({ status: "ok", mailbox_id: data.id, address: data.address, slug: data.slug }));
+}
+
+async function send(args) {
+  const template = parseFlag(args, "--template");
+  const to = parseFlag(args, "--to");
+  const projectId = resolveProjectId(parseFlag(args, "--project"));
+  const p = findProject(projectId);
+  const variables = parseVars(args);
+
+  if (!template) {
+    console.error(JSON.stringify({ status: "error", message: "Missing --template. Options: project_invite, magic_link, notification" }));
+    process.exit(1);
+  }
+  if (!to) {
+    console.error(JSON.stringify({ status: "error", message: "Missing --to <email>" }));
+    process.exit(1);
+  }
+
+  const mailboxId = await resolveMailboxId(projectId, p.service_key);
+
+  const res = await fetch(`${API}/mailboxes/v1/${mailboxId}/messages`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ template, to, variables }),
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data }));
+    process.exit(1);
+  }
+
+  console.log(JSON.stringify({ status: "ok", message_id: data.id, to: data.to, template: data.template }));
+}
+
+async function list(args) {
+  const projectId = resolveProjectId(parseFlag(args, "--project"));
+  const p = findProject(projectId);
+  const mailboxId = await resolveMailboxId(projectId, p.service_key);
+
+  const res = await fetch(`${API}/mailboxes/v1/${mailboxId}/messages`, {
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data }));
+    process.exit(1);
+  }
+
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function get(args) {
+  const messageId = args.find(a => !a.startsWith("--"));
+  const projectId = resolveProjectId(parseFlag(args, "--project"));
+  const p = findProject(projectId);
+
+  if (!messageId) {
+    console.error(JSON.stringify({ status: "error", message: "Missing message_id. Usage: run402 email get <message_id>" }));
+    process.exit(1);
+  }
+
+  const mailboxId = await resolveMailboxId(projectId, p.service_key);
+
+  const res = await fetch(`${API}/mailboxes/v1/${mailboxId}/messages/${messageId}`, {
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data }));
+    process.exit(1);
+  }
+
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "create": await create(args); break;
+    case "send":   await send(args); break;
+    case "list":   await list(args); break;
+    case "get":    await get(args); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

openclaw/scripts/email.mjs

@@ -0,0 +1 @@
+export { run } from "../../cli/lib/email.mjs";

openspec/changes/archive/2026-03-24-project-email/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-24

openspec/changes/archive/2026-03-24-project-email/design.md

@@ -0,0 +1,63 @@
+## Context
+
+Run402's `/mailboxes/v1` API is live in production, providing project-scoped email (one mailbox per project, template-based sending). The MCP server, CLI, and OpenClaw skill need tool/command support so developers can manage mailboxes and send emails from all three interfaces.
+
+The existing codebase follows a strict pattern: MCP tools in `src/tools/`, CLI commands in `cli/lib/`, OpenClaw shims in `openclaw/scripts/`, all kept in sync via the `SURFACE` array in `sync.test.ts`. Email tools follow the same patterns as existing tools (secrets, functions, storage).
+
+All email endpoints use `service_key` auth (same as secrets, SQL, etc.) — no paid/allowance auth needed. One admin-only endpoint (`POST /mailboxes/v1/:id/status`) is excluded from the initial tool surface since it's not developer-facing.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Expose 4 MCP tools: `create_mailbox`, `send_email`, `list_emails`, `get_email`
+- Expose CLI command group: `run402 email {create, send, list, get}` with full `--help` documentation
+- Expose OpenClaw shim re-exporting CLI email module
+- Enforce slug validation client-side (3-63 chars, lowercase alphanumeric + hyphens, no consecutive hyphens)
+- Enforce single-recipient constraint client-side
+- Follow existing tool/test patterns exactly
+- Update `llms-cli.txt` in `~/dev/run402/site/` with email command reference
+
+**Non-Goals:**
+- Admin endpoint (reactivate suspended mailbox) — not developer-facing
+- Webhook registration — defer to a future change
+- Mailbox deletion — available via API but not exposed in initial tool surface
+- Listing mailboxes separately — the API supports it but with 1-per-project constraint, `get_email` on a known mailbox suffices; mailbox ID is returned at creation time
+- Client-side rate limit tracking — the API returns 429 with clear messages
+
+## Decisions
+
+### 1. Four tools, not nine
+
+The API has 9 endpoints but only 4 are needed for the developer workflow: create a mailbox, send an email, list sent messages, get a message. Webhooks, deletion, listing mailboxes, and admin reactivation are deferred.
+
+**Why:** Keeps the tool surface small and focused. The sync test enforces parity — fewer tools means less maintenance. Webhook and delete can be added later as separate SURFACE entries.
+
+### 2. Mailbox ID stored in keystore project record
+
+After `create_mailbox` succeeds, store `mailbox_id` and `mailbox_address` in the project's keystore entry (via `updateProject()`). Subsequent email tools (`send_email`, `list_emails`, `get_email`) accept `project_id` and look up the mailbox ID automatically.
+
+**Why:** Users shouldn't need to remember or pass mailbox IDs — there's only one per project. This mirrors how `site_url` is stored after `deploy_site`. The `StoredProject` interface in `core/src/keystore.ts` already supports arbitrary fields.
+
+### 3. CLI uses `--var key=value` for template variables
+
+Template variables are passed as repeatable `--var` flags: `--var project_name="My App" --var invite_url="https://..."`. The CLI parses these into a `variables` object.
+
+**Why:** Follows CLI conventions for key-value pairs. The alternative (JSON string) is harder to type. The `--var` pattern is familiar from tools like `docker run -e`.
+
+### 4. Slug validation on client side
+
+Both MCP and CLI validate the slug format before sending the API request: 3-63 chars, `^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`, no consecutive hyphens. This gives faster, clearer error messages than waiting for a server 400.
+
+**Why:** Better UX. The server validates too, so this is defense-in-depth, not a replacement.
+
+### 5. No `mailbox_id` parameter on send/list/get
+
+Since there's exactly one mailbox per project, tools look up the mailbox ID from the keystore. If no mailbox is found, the error message suggests running `create_mailbox` first.
+
+**Why:** Simpler API surface. Eliminates a parameter the user would always have to look up. If multi-mailbox support is added later, we can add an optional `mailbox_id` parameter.
+
+## Risks / Trade-offs
+
+- **Keystore dependency for send/list/get** — If a user creates a mailbox outside the CLI/MCP (e.g., via curl), the keystore won't have the mailbox ID. Mitigation: tools can fall back to `GET /mailboxes/v1` to discover the mailbox if not in keystore.
+- **Template enum may grow** — Currently 3 templates. If more are added, the Zod enum needs updating. Mitigation: the server validates templates too, so a stale enum just means a less helpful error message temporarily.
+- **Slug validation drift** — Client and server slug rules could diverge. Mitigation: keep client validation conservative (subset of server rules). Server is authoritative.

openspec/changes/archive/2026-03-24-project-email/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+Run402 now supports project-scoped email at `<slug>@mail.run402.com`. Each project can create one mailbox and send template-based emails (invites, magic links, notifications). The backend is live in production — we need MCP tools, CLI commands, and OpenClaw shims so developers can use email from all three interfaces.
+
+## What Changes
+
+- Add MCP tools: `create_mailbox`, `send_email`, `list_emails`, `get_email`
+- Add CLI command group: `run402 email {create, send, list, get}`
+- Add OpenClaw shims that re-export CLI email module
+- Add unit tests for MCP tools (mock fetch pattern)
+- Update `sync.test.ts` SURFACE array with new email tools/commands
+- Update SKILL.md with email tool references
+
+## Capabilities
+
+### New Capabilities
+- `project-email`: Project-scoped mailbox creation, template-based email sending, and message listing via `/mailboxes/v1` API endpoints
+
+### Modified Capabilities
+<!-- None — this is a new feature with no changes to existing spec-level behavior -->
+
+## Impact
+
+- **MCP server** (`src/tools/`): 4 new tool files + registration in `src/index.ts`
+- **CLI** (`cli/lib/`): New `email.mjs` module + registration in CLI entry point
+- **OpenClaw** (`openclaw/scripts/`): New `email.mjs` shim
+- **Core**: No core changes needed — existing `apiRequest()` and keystore are sufficient
+- **Tests**: New tool test files, sync test updates
+- **API**: Consumes 9 new `/mailboxes/v1` endpoints (service_key auth, one admin-only)