@dbx-tools/shared-email

Validate browser, route, and agent-tool payloads for @dbx-tools/email without importing Node-only code.

Validate a drafted message

import { email, type EmailMessage } from "@dbx-tools/shared-email";

const message: EmailMessage = email.emailMessageSchema.parse({
  to: ["[email protected]"],
  subject: "Report",
  body: "# Done\nThe report is attached.",
  attachments: [{ filename: "report.csv", content: "a,b\n1,2\n" }],
});

The message schema covers recipients, subject, body content, and attachments. Attachments carry inline string content, an optional encoding, and an optional content type. The schema doesn't accept a local path or URL. Read external content in trusted server code, then pass the resulting string through content.

The package also includes send-result and sender-option schemas for routes, approval UIs, and tests.

Validate send results

import { email } from "@dbx-tools/shared-email";

export function parseEmailResult(value: unknown) {
  return email.emailResultSchema.parse(value);
}

const result = parseEmailResult({
  sent: true,
  recipient: "[email protected]",
  from: "[email protected]",
  messageId: "smtp-message-id",
});

emailResultSchema is the shared shape for SMTP sends and outbox writes. Use it for approval UI state and test assertions.

Load sender choices

import { email } from "@dbx-tools/shared-email";

const senders = email.emailSendersSchema.parse(
  await fetch("/api/email/senders").then((response) => response.json()),
);

The sender schema describes the concrete From choices for the current user, the default sender, and whether the list is restricted by policy.

Understand schema and transport limits

• emailAttachmentSchema accepts filename, inline content, encoding, and contentType. It doesn't read files, fetch URLs, or validate whether an encoding matches the content.
• The schemas don't add array minItems constraints because some Model Serving endpoints reject that JSON Schema keyword. The Node sending layer still requires at least one recipient.
• The Node sending layer limits a message to 20 attachments, 10 MiB per decoded attachment, 20 MiB across attachments, and 200,000 body characters.
• Outbox mode lists attachment filenames in the rendered preview but doesn't write attachment payloads as separate files.
• Sender policy, SMTP delivery, approval, and outbox persistence belong to @dbx-tools/email.

Passwordless authentication contracts live in @dbx-tools/shared-auth.