mailbox

一个本地开发邮件接收器：为整台机器运行一个 SMTP 服务器和一个 HTTP API，让每个项目都指向它。邮件永远不会离开你的设备——而是落入一个可检查的收件箱，配有 Web UI、CLI 和面向 AI 代理的 MCP 服务器。

共享一个实例可消除各项目之间的端口冲突：启动一次，即可连接多个。

Install

pnpm add -D @sdk-e/mailbox   # or npm i -D / yarn add -D

或者临时运行：

npx @sdk-e/mailbox

Related MCP server: qmailing MCP server

Quick start

mailbox            # SMTP on :11025, inbox UI on http://localhost:11090

从任何应用（nodemailer、Resend 开发模式等）向 smtp://127.0.0.1:11025 发送邮件，然后：

open http://localhost:11090   # or: mailbox-cli open

Bins

CLI examples

mailbox-cli list
mailbox-cli read 3
mailbox-cli wait "verification code" --timeout 10   # blocks until a new matching message arrives
mailbox-cli clear

wait 只匹配它启动之后到达的消息——在触发发送之前启动它。

Library use

import { startMailbox } from "@sdk-e/mailbox";

const mailbox = await startMailbox({ smtpPort: 0, httpPort: 0 }); // 0 = ephemeral
console.log(mailbox.smtpPort, mailbox.url);
await mailbox.close();

非常适合需要隔离的一次性收件箱的集成测试。

HTTP API（稳定的传输协议）

Configuration

环境变量（如果存在，会加载工作目录中的 .env.local，然后是 .env）：

在本地将应用的邮件程序指向 smtp://127.0.0.1:$MAIL_SMTP_PORT；在生产环境中继续使用你的真实提供商。当 NODE_ENV=production 时，服务器拒绝启动。

Why high ports?

1025/1080（经典的 MailHog 风格默认值）经常冲突。mailbox 默认使用 11025/11090，这样多个 SDK-E 项目可以共享一个实例，而不会相互干扰或影响其他本地工具。

Development

pnpm install
pnpm verify     # format, lint, typecheck, test, build

参见 CONTRIBUTING.md。

License

MIT