# @aws-blocks/bb-email-client 中文文档

规范地址：https://npmcn.com/package/%40aws-blocks/bb-email-client/

版本：0\.2\.0
npm 元数据更新时间：2026-11-02T10:24:54.133Z
中文译文更新时间：2026-11-07T13:41:21.703Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws-blocks/bb-email-client
原文对照：https://npmcn.com/package/%40aws-blocks/bb-email-client/?lang=original
项目主页：https://github.com/aws-devtools-labs/aws-blocks/tree/main/packages/bb-email-client#readme
源码仓库：https://github.com/aws-devtools-labs/aws-blocks

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

- 包体积（解压后）：155 kB，48 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：constructs ^10\.6\.0，aws-cdk-lib ^2\.257\.0
- 首次发布：2026-06-15T23:39:44.200Z
- 最新版本发布：2026-11-02T10:24:53.707Z
- 近 30 天下载量：63083（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

通过Amazon SES发送交易邮件.

## 安装

```sh
npm install @aws-blocks/bb-email-client
```

也可以使用：`pnpm add @aws-blocks/bb-email-client`、`yarn add @aws-blocks/bb-email-client`、`bun add @aws-blocks/bb-email-client`

## README

# @aws- blocks/ bb- 电子邮件客户端

通过Amazon SES发送交易邮件.

> 设计与模拟等价细节 : [设计](https://npmcn.com/package/%40aws-blocks/bb-email-client/DESIGN.md)

## 使用量

```typescript
import { EmailClient } from '@aws-blocks/bb-email-client';

const emailClient = new EmailClient(scope, 'notifications', {
  fromAddress: 'noreply@example.com',
  configurationSet: 'my-tracking-set', // optional
});

// Send a single email
const { messageId } = await emailClient.send({
  to: 'user@example.com',
  subject: 'Welcome!',
  body: 'Thanks for signing up.',
  html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
});
console.log('Sent:', messageId);

// Send a batch of emails (uses SES SendBulkEmail API with inline templates — no setup required)
const result = await emailClient.sendBatch([
  { to: 'alice@example.com', subject: 'Hi Alice', body: 'Hello!' },
  { to: 'bob@example.com', subject: 'Hi Bob', body: 'Hello!' },
]);
const sent = result.results.filter(r => r.status === 'success').length;
const failed = result.results.filter(r => r.status === 'failed').length;
console.log(`Sent: ${sent}, Failed: ${failed}`);
```

## API 密码

### `new EmailClient(scope, id, options)`

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `fromAddress` | `string` | ✅ | 已验证的发送电子邮件地址 |
| `replyTo` | `string[]` | ❌ | 对地址的答复 |
| `configurationSet` | `string` | ❌ | SES 配置设置名称 |

### `emailClient.send(message): Promise<SendResult>`

发送给一个或多个收件人. 回返 `{ messageId: string }`。 。 。 .

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `message.to` | `string | string[]` | 收件人地址 |
| `message.subject` | `string` | 主题行 |
| `message.body` | `string` | 纯文本正文 |
| `message.html` | `string?` | HTML 体 (可选) |
| `message.cc` | `string[]?` | CC 地址( 可选) |
| `message.bcc` | `string[]?` | BCC 地址( 可选) |

### `emailClient.sendBatch(messages): Promise<SendBatchResult>`

使用 SES 发送多封信 `SendBulkEmail` 有内含模板的API. 不需要存储 SES 模板——每个信件的主题、正文和 HTML 都通过 直接通过 `TemplateContent`。 。 。 .

回返 `{ results: Array<{ status, messageId?, error? }> }`。 。 。 .

永远不要让发送失败。 部分失败和全部失败均报告于 `results` 数组( 有 `status: 'failed'`) (中文(简体) ).

没有消息 `html` 仅作为纯文本发送,如同 `send()`页:1 `body` 从未使用 作为HTML的一部分。 无法验证的信件( 见下文) 标记 `failed` 而不是派来的. 信件带有 `html` 自己发送 `SendBulkEmail` 在只有文本的电话之前 命令消息出(并使用SES发送速率)可能与输入顺序不同; `results` 输入顺序.

阵列中的每个消息都是 `EmailMessage` (类型与 `send()`:

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `to` | `string | string[]` | 收件人地址 |
| `subject` | `string` | 主题行 |
| `body` | `string` | 纯文本正文 |
| `html` | `string?` | HTML 体 (可选) |
| `cc` | `string[]?` | CC 地址( 可选) |
| `bcc` | `string[]?` | BCC 地址( 可选) |

### 输入验证

`send()` 财务报告和审定财务报表 `sendBatch()` 以同样的方式验证每个信件,在本地和部署时,在 打电话给SES:

-   每个地址(致、CC、BCC、, `fromAddress` 财务报告和审定财务报表 `replyTo`)必须是有效的电子邮件地址,或者 裸( r)`jane@example.com`)或用平话或引用的字符串所制成的显示名 (单位:千美元)`Jane Doe <jane@example.com>`, (中文(简体) ), `"Doe, Jane" <jane@example.com>`) (中文(简体) ). 地址为 给定: 拒绝周围的白空间和控制字符;
-   每封信最多50个收件人(致+CC+BCC加起来);
-   每封信最多40 MB.

地址不正确或收件人过多 `InvalidInputException`; 超大小信件 掷出 `EmailSendFailedException`内 `sendBatch()` 信件已标记 `failed` 换句话说.

## 处理错误

```typescript
import { EmailErrors } from '@aws-blocks/bb-email-client';
import { isBlocksError } from '@aws-blocks/core';

try {
  await emailClient.send({ to: 'user@example.com', subject: 'Hi', body: 'Hello' });
} catch (e: unknown) {
  if (isBlocksError(e, EmailErrors.SendFailed)) {
    // General send failure — check error message for details
  }
  if (isBlocksError(e, EmailErrors.InvalidInput)) {
    // Malformed input (e.g. invalid email address)
  }
  if (isBlocksError(e, EmailErrors.DomainNotVerified)) {
    // Sending domain not verified in SES
  }
  if (isBlocksError(e, EmailErrors.AccountPaused)) {
    // Account sending is paused by AWS
  }
  if (isBlocksError(e, EmailErrors.RateLimited)) {
    // Transient — safe to retry after backoff
  }
}
```

## 地方发展

本地 dev 模式 (`npm run dev`电子邮件包括:

-   登录到控制台为块( 身体和 HTML 截取) :
    
    ```
    [Email:{id}]
      Recipient: a@example.com, b@example.com
      Subject:   ...
      Body:      ...
      HTML:      ...   (only when html is set)
    ```
    
-   倾向 `.bb-data/{fullId}/emails.json` 供检查
-   用与部署客户端相同的检查来验证,所以本地拒绝的地址或信件在部署时同样被拒绝

## 软件包导出条件

此软件包使用自定义 `"cdk"` 导出条件 :

```json
{
  "exports": {
    ".": {
      "cdk": "./dist/index.cdk.js",
      "aws-runtime": "./dist/index.aws.js",
      "default": "./dist/index.mock.js"
    }
  }
}
```

> **说明:** 这个 `"cdk"` 条件是一个区块框架公约,由区块建筑解决 工具链( tsx 带有 `--conditions=cdk`) (中文(简体) ). 没错 **没有** 内置节点js条件和意愿 未在标准中解析 `node` 或者说 `ts-node` 除非你通过 `--conditions=cdk` 当然.

## 限制

-   **每个消息接收者**: 每封信最多50个收件人(向+CC+BCC合并)
-   **批量 API 目的地**:50个目的地 `SendBulkEmail` API 呼叫( 通过块自动处理)
-   **信件大小**: 40 MB 每封信
-   **SES 沙盒率**: 1个电子邮件/秒(要求生产,以便增加吞吐量)

> **说明:** 模拟器和 AWS 运行时间执行每个消息接收器和大小限制 本地呼叫 SES( 参见 [输入验证](https://npmcn.com/package/%40aws-blocks/bb-email-client/#readme-input-validation): `send()` 抛出,和 `sendBatch()` 将违反记录为失败的条目 `results`。 。 。 .

## 常见问题

### @aws-blocks/bb-email-client 是什么？

通过Amazon SES发送交易邮件\.

### 如何安装 @aws-blocks/bb-email-client？

在项目目录运行 npm install @aws-blocks/bb-email-client，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.6\.0）、aws-cdk-lib（^2\.257\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-blocks/bb-email-client 支持 TypeScript 吗？

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

### @aws-blocks/bb-email-client 支持 ESM 还是 CommonJS？

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

### @aws-blocks/bb-email-client 可以商用吗？

@aws-blocks/bb-email-client 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-blocks/bb-email-client 的下载量有多少？

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

### @aws-blocks/bb-email-client 还在维护吗？

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