mailbox

로컬 개발용 메일 싱크(mail sink): 머신 전체에서 하나의 SMTP 서버와 HTTP API를 실행하고 모든 프로젝트가 이를 가리키게 하세요. 이메일은 기기를 벗어나지 않으며, 대신 웹 UI, CLI, AI 에이전트용 MCP 서버가 있는 검사 가능한 받은 편지함에 도착합니다.

공유 인스턴스 하나로 프로젝트별 포트 충돌을 없앨 수 있습니다: 한 번 시작하면 여러 프로젝트가 연결할 수 있습니다.

설치

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

또는 임시로 실행:

npx @sdk-e/mailbox

빠른 시작

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

어떤 앱에서든 smtp://127.0.0.1:11025로 메일을 보내세요(nodemailer, Resend 개발 모드 등). 그런 다음:

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

바이너리

CLI 예시

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는 시작한 후에 도착하는 메시지만 매칭합니다 — 메일 전송을 트리거하기 전에 먼저 시작하세요.

라이브러리 사용

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 (안정적인 와이어 프로토콜)

구성

환경 변수(작업 디렉터리에 .env.local, 그다음 .env가 있으면 로드됨):

앱의 메일러를 로컬에서 smtp://127.0.0.1:$MAIL_SMTP_PORT로 지정하세요. 프로덕션에서는 기존 실제 제공업체를 계속 사용하세요. 서버는 NODE_ENV=production일 때 시작을 거부합니다.

왜 높은 포트인가?

1025/1080(기존 MailHog 스타일 기본값)은 충돌이 잦습니다. mailbox는 기본값으로 11025/11090을 사용하므로 여러 SDK-E 프로젝트가 서로 또는 다른 로컬 도구와 충돌하지 않고 단일 인스턴스를 공유할 수 있습니다.

개발

Node >= 20 및 pnpm >= 11 필요.

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

CONTRIBUTING.md를 참조하세요.

라이선스

MIT