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

通过Amazon SES发送交易邮件.

设计与模拟等价细节 : 设计

使用量

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

const emailClient = new EmailClient(scope, 'notifications', {
  fromAddress: '[email protected]',
  configurationSet: 'my-tracking-set', // optional
});

// Send a single email
const { messageId } = await emailClient.send({
  to: '[email protected]',
  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: '[email protected]', subject: 'Hi Alice', body: 'Hello!' },
  { to: '[email protected]', 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)

emailClient.send(message): Promise<SendResult>

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

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():

输入验证

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

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

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

处理错误

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

try {
  await emailClient.send({ to: '[email protected]', 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: [email protected], [email protected]
    Subject:   ...
    Body:      ...
    HTML:      ...   (only when html is set)
  

• 倾向 .bb-data/{fullId}/emails.json 供检查
• 用与部署客户端相同的检查来验证,所以本地拒绝的地址或信件在部署时同样被拒绝

软件包导出条件

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

{
  "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( 参见 输入验证: send() 抛出,和 sendBatch() 将违反记录为失败的条目 results。 。 。 .