# @bitbaum/mail-kit 中文文档

规范地址：https://npmcn.com/package/%40bitbaum/mail-kit/

版本：0\.2\.0
npm 元数据更新时间：2026-10-22T09:11:16.679Z
中文译文更新时间：2026-11-08T04:01:23.805Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bitbaum/mail-kit
原文对照：https://npmcn.com/package/%40bitbaum/mail-kit/?lang=original
项目主页：https://github.com/bitbaum/mail-kit#readme
源码仓库：https://github.com/bitbaum/mail-kit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：64.2 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-09-05T09:50:00.044Z
- 最新版本发布：2026-10-22T09:11:16.093Z
- 近 30 天下载量：10887（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

舰队的一个电子邮件层:在原始接取之上重新发送,零依赖性,诚实的永不扔出结果,沙盒/位置持有者守护,共享-发件人大会编码一次.

## 安装

```sh
npm install @bitbaum/mail-kit
```

也可以使用：`pnpm add @bitbaum/mail-kit`、`yarn add @bitbaum/mail-kit`、`bun add @bitbaum/mail-kit`

## README

# @bitbaum/ mail- kit (英语)

舰队的 **一个** 电子邮件层。 一个供应商(Resend),一个Env合同,一个 调用形状,零运行时间依赖.

因为车队增长 ~ 12 发声的电子邮件执行跨3个 提供商的风格, 以及一个死去的 SMTP 证书 沉默了两个应用程序的外出邮件 几个月没人注意到 统一即是修行.

## 安装

```bash
pnpm add @bitbaum/mail-kit
```

## 使用

```ts
import { sendMail, isMailConfigured, mailHealth, conventionalFrom } from "@bitbaum/mail-kit";

const result = await sendMail({
  to: "person@example.ch",
  subject: "Your invoice",
  html: "<p>…</p>",
  attachments: [{ filename: "invoice.pdf", content: pdfBuffer, contentType: "application/pdf" }],
});

if (!result.sent) {
  // result.error, result.status?, result.retryable — sendMail NEVER throws.
  logger.error("invoice email failed", result);
}
```

-   **`sendMail` 从来没有扔过.** 服务器动作中发生的邮件错误 到达任何人,并摧毁形式;a `{ sent: false }` 你必须看 可交付。 检查分娩事项的呼叫者 `.sent`。 。 。 .
-   **`isMailConfigured()`** - 大门流出 _依赖_ 在邮件到达 (密码重置,发票). 占位钥匙和生产沙盒 发件人( e)`@resend.dev`计为 **未配置**: 外观配置和 给任何人.
-   **`mailHealth()`** - 键-有效性+域-状态探测器 `/api/health`。 。 。 . 过往的探测器不能证明交货;只有真正的发送才能证明.
-   **`options.idempotencyKey`** ——从克伦斯克/克伦斯通过,如此重试的工作 无法双发( 24 h 的复发).

## 每个应用程序一个地址: `hello@<host>`

每个应用程序都有自己的主机地址,客户可以猜测: `hello@skif.orangecat.ch`,以及 `hello@murphys-bar.ch` 一旦一个网站有自己的 域名. `appAddress(url)` 建造; `appAddressFromEnv()` 读取 `MAIL_ADDRESS` 或从 `APP_URL` 编号 : `NEXT_PUBLIC_SITE_URL` 编号 : `AUTH_URL`。 。 。 .

`sendMail` 把地址放进去 **答复** 每个消息( 除非呼叫) 设置自己的,或已经从它发送。 邮件仍然通过共享 发送器直到每个主机都能自己签名——但每个答案都到达了应用.

## 邮寄到应用程序

车队的邮件网关接收每个应用程序主机,检查SPF/DKIM/DMARC, 邮编 a `InboundMail` 改为 `/api/mail/inbound`,与 `MAIL_INBOUND_SECRET` (单位:千美元)`x-mail-signature: t=…,v1=hmac`) (中文(简体) ). 应用程序的一面 线条:

```ts
// app/api/mail/inbound/route.ts
import { inboundHandler } from "@bitbaum/mail-kit";
export const POST = inboundHandler({ onMail: (mail) => saveAndTriage(mail) });
```

未署名、被篡改、陈旧( > 5分)或过量的交货在交货前被拒绝 您的代码运行; 抛出 `onMail` 回答500,所以网关重复.

## AI 分类法

`triageMail(mail, complete, context)` 询问模式( 任意 `complete()` - 那个 ai-形式/ai-kit形状)用于 `kind`, (中文(简体) ), `urgency`,单行 `summary`,则 发件人 `language` 财务报告和审定财务报表 `needsHuman`。它从不扔:没有模型,或者胡说八道 答案来自简单的规则,标记 `by: "rules"`指示 在电子邮件中.

## 信封合同(全部)

| 瓦尔 | 含义 |
| --- | --- |
| `RESEND_API_KEY` | 需要发送( 车队密钥 : `/opt/fleet/env`(中文(简体) ) |
| `RESEND_FROM` | 发件人 - `Name <addr>` 或赤裸的地址(如果每次拨打都可用) `from`(中文(简体) ) |
| `MAIL_ADDRESS` | 应用程序自己的地址; 可选地址, 来源于应用程序的 URL |
| `MAIL_INBOUND_SECRET` | 从网关验证邮件( 车队密钥 : `/opt/fleet/env`(中文(简体) ) |

## 舰队公约

-   共享的Resend账户在 **免费等级**: 1个已核实域, **每天100个电子邮件**,3000个/月. 击打每天的盖子表面 `{ sent: false, status: 429, retryable: true }`。 。 。 .
-   仅 `loki.orangecat.ch` 被验证,所以每个应用程序发送为 `<app>@fleetcrown.orangecat.ch` —— 说 `conventionalFrom("My App")` 建造它.
-   盒子上的每日金丝雀发送一个真正的电子邮件,当它发出时会提醒Telegram 失败——不是这个包,而是证明交货继续起作用.

## 这不是什么

-   不是模板引擎——应用程序拥有他们的HTML.
-   不是排队.. `retryable` 告诉一个打电话的人 _是否为_ 重试可以帮助; 日程安排一是打电话者的决定.
-   不是批量的——通讯通过Listmonk.

* * *

部分 **[位点](https://bitbaum.orangecat.ch/)** 开放的AI-本土产品 在苏黎世建造的基础设施。 这里的每个软件包都列出使用该软件的应用程序: **[应用程序使用邮件 kit](https://bitbaum.orangecat.ch/packages/#mail-kit)**。 。 。 .

## 常见问题

### @bitbaum/mail-kit 是什么？

舰队的一个电子邮件层:在原始接取之上重新发送,零依赖性,诚实的永不扔出结果,沙盒/位置持有者守护,共享-发件人大会编码一次\.

### 如何安装 @bitbaum/mail-kit？

在项目目录运行 npm install @bitbaum/mail-kit，或使用 pnpm add / yarn add / bun add。

### @bitbaum/mail-kit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bitbaum/mail-kit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bitbaum/mail-kit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bitbaum/mail-kit 可以商用吗？

@bitbaum/mail-kit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bitbaum/mail-kit 的下载量有多少？

根据 npm 官方下载统计，@bitbaum/mail-kit 在 2026/10/08 – 2026/11/06 这 30 天内被下载 10,887 次，日均约 363 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bitbaum/mail-kit 还在维护吗？

最新版本 0\.2\.0 发布于 2026/10/22（17 天前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/09/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。