feat(email): attachments on mailbox send (SDK + CLI + MCP + docs)

Surface for run402's outbound email attachments (gateway shipped in kychee-com/run402-private #467). SDK SendEmailOptions.attachments + EmailAttachment(Meta) types + local template-mode guard; CLI 'email send --attach <path>[:content-type]' (repeatable, ext-inferred type); MCP send-email attachments param; llms-sdk/llms-cli/llms-mcp docs. Tests: SDK 28, MCP 8, CLI-argv 119 green. NOT published to npm — version bump + publish left for a deliberate release.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: MajorTal

cli-argv.test.mjs

@@ -1628,3 +1628,57 @@ describe("CLI JSON-only output contract (v3.x cleanup)", () => {
     assert.ok(Array.isArray(parsed.checks), "doctor stdout should have checks array");
   });
 });
+
+describe("email --attach parsing", () => {
+  let attachDir;
+  before(() => {
+    attachDir = mkdtempSync(join(tmpdir(), "run402-attach-test-"));
+  });
+  after(() => {
+    rmSync(attachDir, { recursive: true, force: true });
+  });
+
+  it("parses a single --attach and infers content-type from the extension", async () => {
+    const { parseAttachments } = await import("./cli/lib/email.mjs");
+    const p = join(attachDir, "foo.pdf");
+    writeFileSync(p, "PDFDATA");
+    const out = parseAttachments(["--attach", p]);
+    assert.deepEqual(out, [
+      { filename: "foo.pdf", content_base64: Buffer.from("PDFDATA").toString("base64"), content_type: "application/pdf" },
+    ]);
+  });
+
+  it("parses repeated --attach flags into multiple entries", async () => {
+    const { parseAttachments } = await import("./cli/lib/email.mjs");
+    const a = join(attachDir, "a.csv");
+    const b = join(attachDir, "b.png");
+    writeFileSync(a, "x,y");
+    writeFileSync(b, "PNG");
+    const out = parseAttachments(["--attach", a, "--attach", b]);
+    assert.equal(out.length, 2);
+    assert.equal(out[0].content_type, "text/csv");
+    assert.equal(out[1].content_type, "image/png");
+  });
+
+  it("honors an explicit :content-type suffix over the extension", async () => {
+    const { parseAttachments } = await import("./cli/lib/email.mjs");
+    const p = join(attachDir, "data.bin");
+    writeFileSync(p, "raw");
+    const out = parseAttachments(["--attach", `${p}:text/csv`]);
+    assert.equal(out[0].filename, "data.bin");
+    assert.equal(out[0].content_type, "text/csv");
+  });
+
+  it("rejects an unreadable attachment path before sending", async () => {
+    const { parseAttachments } = await import("./cli/lib/email.mjs");
+    const env = await expectExit1(() => parseAttachments(["--attach", join(attachDir, "nope.pdf")]));
+    assert.equal(env.code, "BAD_USAGE");
+    assert.match(env.message, /Cannot read attachment file/);
+  });
+
+  it("rejects --attach with no value", async () => {
+    const { parseAttachments } = await import("./cli/lib/email.mjs");
+    const env = await expectExit1(() => parseAttachments(["--attach"]));
+    assert.equal(env.code, "BAD_USAGE");
+  });
+});

cli/lib/email.mjs

@@ -1,8 +1,72 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail, parseFlagJson } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs } from "./argparse.mjs";
 
+// Extension → content-type for `--attach <path>` without an explicit `:type`.
+const ATTACH_EXT_CONTENT_TYPES = {
+  pdf: "application/pdf",
+  csv: "text/csv",
+  txt: "text/plain",
+  json: "application/json",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  zip: "application/zip",
+  html: "text/html",
+  xml: "application/xml",
+};
+const ATTACH_MIME_RE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i;
+
+function inferAttachmentContentType(path) {
+  const ext = (path.split(".").pop() ?? "").toLowerCase();
+  return ATTACH_EXT_CONTENT_TYPES[ext] ?? "application/octet-stream";
+}
+
+/**
+ * Parse repeatable `--attach <path>[:content-type]` flags into the SDK
+ * attachment shape. The `:content-type` suffix is recognized only when the tail
+ * after the last `:` looks like a MIME type, so paths containing a colon (e.g. a
+ * Windows drive) are not mis-split.
+ */
+export function parseAttachments(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== "--attach") continue;
+    const raw = args[++i];
+    if (typeof raw !== "string" || raw.length === 0 || raw.startsWith("--")) {
+      fail({ code: "BAD_USAGE", message: "--attach requires a <path>[:content-type] value" });
+    }
+    let path = raw;
+    let contentType;
+    const colon = raw.lastIndexOf(":");
+    if (colon > 0 && ATTACH_MIME_RE.test(raw.slice(colon + 1))) {
+      path = raw.slice(0, colon);
+      contentType = raw.slice(colon + 1).toLowerCase();
+    }
+    let bytes;
+    try {
+      bytes = readFileSync(path);
+    } catch (err) {
+      fail({
+        code: "BAD_USAGE",
+        message: `Cannot read attachment file: ${path}`,
+        details: { error: String((err && err.message) || err) },
+      });
+    }
+    out.push({
+      filename: basename(path),
+      content_base64: bytes.toString("base64"),
+      content_type: contentType ?? inferAttachmentContentType(path),
+    });
+  }
+  return out;
+}
+
 const HELP = `run402 email — Send emails from your project
 
 Usage:
@@ -45,6 +109,7 @@ Webhook subcommands:
 Send modes:
   Template:  --template <name> --var key=value [--var ...]  OR --vars '{"k":"v",...}'
   Raw HTML:  --subject "..." --html "..." [--text "..."]    (both --subject and --html required)
+  Raw HTML also supports: --attach <path>[:content-type] (repeatable; max 5, 7 MB total)
   Both modes support: --from-name "Display Name" --project <id>
 
 Choosing a mailbox:
@@ -65,6 +130,8 @@ Examples:
     --var project_name="My App" --var invite_url="https://example.com/invite/abc"
   run402 email send --to user@example.com --subject "Welcome!" \\
     --html "<h1>Hello</h1>" --from-name "My App"
+  run402 email send --to user@example.com --subject "Your receipt" \\
+    --html "<p>Attached.</p>" --attach ./receipt.pdf
   run402 email list --limit 50
   run402 email info
   run402 email get msg_abc123
@@ -86,7 +153,7 @@ const SUB_HELP = {
 Usage:
   run402 email send --to <email> --template <name> --var key=value [--var ...]
   run402 email send --to <email> --template <name> --vars '{"k":"v",...}'
-  run402 email send --to <email> --subject "..." --html "..." [--text "..."]
+  run402 email send --to <email> --subject "..." --html "..." [--text "..."] [--attach <path> ...]
 
 Options:
   --to <email>        Recipient email address (required; single recipient)
@@ -97,6 +164,9 @@ Options:
   --subject "..."     Subject line (raw HTML mode; required with --html)
   --html "..."        HTML body (raw HTML mode; required with --subject)
   --text "..."        Plain-text body (raw HTML mode; optional)
+  --attach <path>[:content-type]  Attach a file (raw HTML mode only; repeatable;
+                      max 5, ≤ 7 MB total). Content-type is inferred from the
+                      extension when the :content-type suffix is omitted.
   --from-name "..."   Display name for the From header
   --mailbox <slug|id> Target mailbox (required if the project has more than one)
   --project <id>      Project ID (defaults to the active project)
@@ -258,7 +328,7 @@ async function create(args) {
 }
 
 async function send(args) {
-  const valueFlags = ["--template", "--to", "--subject", "--html", "--text", "--from-name", "--project", "--vars", "--var", "--mailbox"];
+  const valueFlags = ["--template", "--to", "--subject", "--html", "--text", "--from-name", "--project", "--vars", "--var", "--mailbox", "--attach"];
   validateArgs(args, valueFlags);
   const template = strictFlagValue(args, "--template");
   const to = strictFlagValue(args, "--to");
@@ -269,6 +339,7 @@ async function send(args) {
   const mailbox = strictFlagValue(args, "--mailbox");
   const projectId = resolveProjectId(strictFlagValue(args, "--project"));
   const variables = parseVars(args);
+  const attachments = parseAttachments(args);
 
   if (!to) {
     fail({ code: "BAD_USAGE", message: "Missing --to <email>" });
@@ -284,6 +355,7 @@ async function send(args) {
       text: text ?? undefined,
       from_name: fromName ?? undefined,
       mailbox: mailbox ?? undefined,
+      attachments: attachments.length ? attachments : undefined,
     });
     console.log(JSON.stringify({ message_id: data.message_id, to: data.to, template: data.template, subject: data.subject, sent: true }));
   } catch (err) {

cli/llms-cli.txt

@@ -1272,7 +1272,7 @@ Templates: `project_invite` (project_name, invite_url), `magic_link` (project_na
 - `run402 email create <slug> [--project <id>]` — create mailbox at `<slug>@mail.run402.com`. NOT idempotent: a conflict (slug already in use, address in cooldown, or the project already has 5 mailboxes) returns a 409 error rather than an existing mailbox.
 - `run402 email status [--mailbox <slug|id>] [--project <id>]` — show mailbox info (ID, address, slug)
 - `run402 email send --template <name> --to <email> [--var key=value ...] [--from-name <name>] [--mailbox <slug|id>] [--project <id>]`
-- `run402 email send --to <email> --subject <subject> --html <html> [--text <text>] [--from-name <name>] [--mailbox <slug|id>] [--project <id>]`
+- `run402 email send --to <email> --subject <subject> --html <html> [--text <text>] [--attach <path>[:content-type] ...] [--from-name <name>] [--mailbox <slug|id>] [--project <id>]`
 - `run402 email list [--direction <inbound|outbound>] [--mailbox <slug|id>] [--project <id>]` — lists BOTH sent + received by default; `--direction inbound` lists received replies (the reconciliation backstop if a reply_received webhook is lost)
 - `run402 email get <message_id> [--mailbox <slug|id>] [--project <id>]`
 - `run402 email reply <message_id> --html <html> [--text <text>] [--subject <subject>] [--from-name <name>] [--mailbox <slug|id>] [--project <id>]` — reply to an inbound message (threads via In-Reply-To)
@@ -1286,7 +1286,7 @@ Templates: `project_invite` (project_name, invite_url), `magic_link` (project_na
 - `run402 email webhooks deliveries [--status <pending|in_flight|delivered|failed_permanent>] [--mailbox <slug|id>] [--project <id>]` — list durable delivery rows. Delivery is at-least-once with bounded retries + backoff; `failed_permanent` is the dead-letter queue. The delivered body is the canonical envelope `{ id, type, created_at, schema_version, idempotency_key, payload }` — consumers MUST dedupe on `idempotency_key`.
 - `run402 email webhooks redrive <delivery_id> [--mailbox <slug|id>] [--project <id>]` — re-queue a dead-lettered (failed_permanent) delivery for another attempt
 
-Raw HTML: `--subject` (max 998 chars) + `--html` (max 1MB). Plaintext auto-generated from HTML if `--text` omitted. `--from-name` sets display name on From header (both modes): `"My App" <slug@mail.run402.com>`.
+Raw HTML: `--subject` (max 998 chars) + `--html` (max 1MB). Plaintext auto-generated from HTML if `--text` omitted. `--attach <path>[:content-type]` attaches a file (raw HTML mode only; repeatable, max 5, ≤ 7 MB total; content-type inferred from the extension when the suffix is omitted). `--from-name` sets display name on From header (both modes): `"My App" <slug@mail.run402.com>`.
 
 Slug rules: 3-63 chars, lowercase alphanumeric + hyphens, no consecutive hyphens. `--project` defaults to the active project.
 

llms-mcp.txt

@@ -388,7 +388,7 @@ Fixed platform-managed jobs. These tools do not run arbitrary Docker images; the
 - `passkey_login_options` / `passkey_login_verify` — WebAuthn passkey login. Params: `project_id`, `app_origin`, `email?` then `challenge_id`, `response`.
 - `list_passkeys` / `delete_passkey` — list or delete the authenticated user's passkeys. Params: `project_id`, `access_token`, `passkey_id?`.
 - `create_mailbox` / `get_mailbox` / `delete_mailbox` — up to 5 mailboxes per project at `<slug>@mail.run402.com`. Read/send/webhook tools take an optional `mailbox` (slug or `mbx_…` id) to choose one; omitting it on a project with more than one mailbox returns an ambiguity error naming the slugs. `create_mailbox` is NOT idempotent — a 409 (slug in use / cooldown / project at its 5-mailbox limit) is surfaced as an error, not recovered. `delete_mailbox` requires `confirm: true` and takes the target via `mailbox_id` (slug or id).
-- `send_email` — template (`project_invite`, `magic_link`, `notification`) or raw HTML. Single recipient. Params: `project_id`, `to`, `template?` + `variables?` OR `subject?` + `html?` + `text?`, `from_name?`, `in_reply_to?`, `mailbox?`.
+- `send_email` — template (`project_invite`, `magic_link`, `notification`) or raw HTML. Single recipient. Params: `project_id`, `to`, `template?` + `variables?` OR `subject?` + `html?` + `text?` + `attachments?`, `from_name?`, `in_reply_to?`, `mailbox?`. `attachments?` (raw mode only): `{ filename, content_base64, content_type }[]`, max 5, ≤ 7 MB total.
 - `list_emails` / `get_email` — read messages. Both take an optional `mailbox`.
 - `get_email_raw` — return raw RFC-822 bytes for DKIM / zk-email verification (inbound only). Params: `project_id`, `message_id`, `mailbox?`.
 - `register_mailbox_webhook` / `list_mailbox_webhooks` / `get_mailbox_webhook` / `update_mailbox_webhook` / `delete_mailbox_webhook` — email-event webhooks (events: `delivery`, `bounced`, `complained`, `reply_received`). Each takes an optional `mailbox`.

sdk/llms-sdk.txt

@@ -1022,6 +1022,9 @@ getMailbox(projectId): Promise<MailboxInfo>
 deleteMailbox(projectId, mailboxId?): Promise<void>
 
 send(projectId, opts: SendEmailOptions): Promise<SendEmailResult>
+  // opts.attachments?: { filename, content_base64, content_type }[] — RAW MODE
+  // ONLY (subject + html, not template). Max 5; ≤ 7 MB total decoded. Sent as a
+  // multipart/mixed MIME. Sent messages echo attachments_meta (names/types/sizes).
 list(projectId, opts?: { limit?, after?, direction? }): Promise<EmailSummary[]>
   // direction?: "inbound" | "outbound" — omit for BOTH. direction:"inbound" lists
   // received replies (each EmailSummary carries `direction`) and is the
@@ -1053,7 +1056,7 @@ info(projectId): Promise<MailboxInfo>
 delete(projectId, mailboxId?): Promise<void>
 ```
 
-Templates: `project_invite`, `magic_link`, `notification`. Or pass `subject` + `html` for raw mode. Tier rate limits: prototype 10/day, hobby 50/day, team 500/day.
+Templates: `project_invite`, `magic_link`, `notification`. Or pass `subject` + `html` for raw mode. Raw mode also accepts `attachments` (max 5, ≤ 7 MB total) — a multipart/mixed MIME is sent. Tier rate limits: prototype 10/day, hobby 50/day, team 500/day.
 
 ### `r.senderDomain`
 

sdk/src/namespaces/email.test.ts

@@ -251,6 +251,42 @@ describe("email.send", () => {
     );
     assert.equal(calls.length, 0);
   });
+
+  it("includes attachments in the raw-mode send body", async () => {
+    const { fetch, calls } = mockFetch(() =>
+      jsonResponse({ message_id: "msg_1", to: "user@example.invalid", template: null, subject: "test", status: "sent", sent_at: "2026-05-01T18:30:14.904Z" }),
+    );
+    const sdk = makeSdk(makeCreds(), fetch);
+    const attachments = [{ filename: "a.pdf", content_base64: "JVBERi0=", content_type: "application/pdf" }];
+    await sdk.email.send("prj_known", {
+      to: "user@example.invalid",
+      subject: "test",
+      html: "<p>hi</p>",
+      attachments,
+      mailbox: "mbx_known",
+    });
+    assert.deepEqual(JSON.parse(calls[0]!.body as string).attachments, attachments);
+  });
+
+  it("rejects attachments in template mode before requesting", async () => {
+    const { fetch, calls } = mockFetch(() => {
+      throw new Error("unexpected fetch for template+attachments");
+    });
+    const sdk = makeSdk(makeCreds(), fetch);
+    await assert.rejects(
+      sdk.email.send("prj_known", {
+        to: "user@example.invalid",
+        template: "notification",
+        variables: { project_name: "X", message: "hi" },
+        attachments: [{ filename: "a.pdf", content_base64: "JVBERi0=", content_type: "application/pdf" }],
+      }),
+      (err: unknown) =>
+        err instanceof LocalError &&
+        err.context === "sending email" &&
+        /raw mode/i.test(err.message),
+    );
+    assert.equal(calls.length, 0);
+  });
 });
 
 describe("email message ids", () => {

sdk/src/namespaces/email.ts

@@ -54,6 +54,20 @@ export type EmailTemplate = "project_invite" | "magic_link" | "notification";
 /** Selects a target mailbox on a multi-mailbox project: a mailbox id (`mbx_…`) or a slug. */
 export type MailboxSelector = string;
 
+/** A single binary attachment (raw mode only). `content_base64` is the file's bytes, base64-encoded. */
+export interface EmailAttachment {
+  filename: string;
+  content_base64: string;
+  content_type: string;
+}
+
+/** Attachment metadata recorded on a sent message (names/types/sizes — never the bytes). */
+export interface EmailAttachmentMeta {
+  filename: string;
+  content_type: string;
+  size_bytes: number;
+}
+
 export interface SendEmailOptions {
   to: string;
   template?: EmailTemplate;
@@ -62,6 +76,12 @@ export interface SendEmailOptions {
   html?: string;
   text?: string;
   from_name?: string;
+  /**
+   * Binary attachments — RAW MODE ONLY (with `subject` + `html`, not `template`).
+   * At most 5; each ≤ 7 MB and ≤ 7 MB total (decoded). The platform sends a
+   * multipart/mixed MIME when present.
+   */
+  attachments?: EmailAttachment[];
   in_reply_to?: string;
   /**
    * Target mailbox (slug or `mbx_…` id) on a project that has more than one.
@@ -93,6 +113,8 @@ export interface EmailSummary {
   to: string;
   status: string;
   created_at: string;
+  /** Present (non-null) when the send carried attachments; names/types/sizes only. */
+  attachments_meta?: EmailAttachmentMeta[] | null;
 }
 
 export interface EmailDetail {
@@ -102,6 +124,8 @@ export interface EmailDetail {
   status: string;
   variables: Record<string, string>;
   created_at: string;
+  /** Present (non-null) when the send carried attachments; names/types/sizes only. */
+  attachments_meta?: EmailAttachmentMeta[] | null;
   replies?: Array<{
     id: string;
     from: string;
@@ -504,6 +528,13 @@ export class Email {
         "sending email",
       );
     }
+    const hasAttachments = Array.isArray(opts.attachments) && opts.attachments.length > 0;
+    if (hasAttachments && isTemplate) {
+      throw new LocalError(
+        "Attachments are only supported in raw mode (`subject` + `html`), not with `template`.",
+        "sending email",
+      );
+    }
 
     const { id, serviceKey } = await this.resolveMailbox(projectId, opts.mailbox);
     const body: Record<string, unknown> = { to: opts.to };
@@ -514,6 +545,7 @@ export class Email {
       body.subject = opts.subject;
       body.html = opts.html;
       if (opts.text !== undefined) body.text = opts.text;
+      if (hasAttachments) body.attachments = opts.attachments;
     }
     if (opts.from_name !== undefined) body.from_name = opts.from_name;
     if (opts.in_reply_to !== undefined) body.in_reply_to = opts.in_reply_to;

src/tools/send-email.test.ts

@@ -171,6 +171,30 @@ describe("send_email tool", () => {
     assert.equal(parsed.from_name, "My App");
   });
 
+  it("forwards attachments in the raw-mode send body", async () => {
+    let capturedBody: string | undefined;
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      if (isMailboxListGet(url, init)) return mailboxListResponse();
+      capturedBody = init?.body as string;
+      return new Response(
+        JSON.stringify({ message_id: "msg-004", status: "sent", to: "user@example.com", subject: "Receipt", template: null, sent_at: "2026-05-01T00:00:00.000Z" }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    const attachments = [{ filename: "receipt.pdf", content_base64: "JVBERi0=", content_type: "application/pdf" }];
+    const result = await handleSendEmail({
+      project_id: "proj-001",
+      to: "user@example.com",
+      subject: "Receipt",
+      html: "<p>Attached.</p>",
+      attachments,
+    });
+
+    assert.equal(result.isError, undefined);
+    assert.deepEqual(JSON.parse(capturedBody!).attachments, attachments);
+  });
+
   it("returns error when neither template nor subject/html provided", async () => {
     const result = await handleSendEmail({
       project_id: "proj-001",