@growth-labs/mailer

中文文档
0.8.2发布于 2026/10/27TypeScriptES Module近 30 天下载 4945

基于队列的Astro + Cloudflare 电子邮件发送引擎. 通讯订阅有双选入,活动发送,开放/点击跟踪,不订阅管理. 使用 Cloudflare Quees 来进行Aync送出.

中文使用文档
文档目录10 节
  1. 何时使用此 vs @growth-labs/email
  2. 配置
  3. 没有交货路线的部件
  4. 生产模式
  5. 输入什么
  6. D1 表格(前缀) gl_ (中文(简体) )
  7. 装订
  8. 电子邮件发送流程
  9. 密钥模式
  10. 分析事件

@ growth-labs/ 邮件

基于队列的Astro + Cloudflare 电子邮件发送引擎. 通讯订阅有双选入,活动发送,开放/点击跟踪,不订阅管理. 使用 Cloudflare Quees 来进行Aync送出.

"发动机,不是司机。" 此软件包发送邮件 。 寄送什么,消费者关心的是谁(如:. @fulcrum/dispatch 层层编辑智能在上.

如果您只需要从没有用户状态或队列的工人那里立即发送交易, 请使用 @growth-labs/email 换句话说.

Astro 6 注: 注入的路由为 D1 和队列绑定 cloudflare:workers env; 无 locals.runtime shim是必须的.

何时使用此 vs @growth-labs/email

使用 @growth-labs/mailer (本套)用于通讯和宣传活动 工作流程。 使用 @growth-labs/email 交易一次性发送. 见 @growth-labs/email 读取完全区分.

两种集成程序都通过 阿斯特罗的 astro:config:done 类型注射。 任何消费者拥有的申报 所需经费 virtual:growth-labs/mailer/config;运行时路由选择不变.

配置

import mailer from '@growth-labs/mailer'

mailer({
  senderName: 'FEDweek',
  fromAddress: '[email protected]',
  replyTo: '[email protected]',
  d1Binding: 'SITE_DB',
  queueBinding: 'EMAIL_QUEUE',
  turnstileSiteKey: '...',
  turnstileSecretBinding: 'TURNSTILE_SECRET_KEY', // Optional; this is the default
  doubleOptIn: true,
  topics: ['daily-digest', 'breaking-news'],     // Optional topic-based subscriptions
  signingSecretBinding: 'MAILER_SIGNING_SECRET', // Optional; this is the default
  siteUrl: 'https://fedweek.com',
  brand: {
    logoUrl: 'https://media.fedweek.com/logos/email.png',
    primaryColor: '#1a365d',
    accentColor: '#e53e3e',
    footerText: '© FEDweek. All rights reserved.',
  },
  analyticsEnabled: true,                        // Emit email events to @growth-labs/analytics
  analyticsBinding: 'ANALYTICS',                 // WAE binding used when analytics is enabled
  webhookSignature: {
    enabled: true,
    secret: import.meta.env.MAILER_WEBHOOK_SECRET,
  },
})

这项合并登记了下列通讯路线和组成部分. 对于新订阅者,订阅路由会记录订阅者并发送一个 何时确认电子邮件 doubleOptIn 已启用,或未启用的欢迎电子邮件.

没有交货路线的部件

使用 mailerComponents 改为 mailer 渲染时 SubscribeForm 与 由消费者拥有的端点,或者在私人预览中无法交付:

import { mailerComponents } from '@growth-labs/mailer'

mailerComponents({
  turnstileSiteKey: 'public-site-key',
  subscribePath: '/api/newsletter/subscribe', // Optional; this is the default
  topics: ['daily-digest'],                 // Optional
})

这只安装现有的窗体配置 Vite 插件 。 它不会注射 路径或跟踪中间软件,不需要D1、队列、发送者或秘密绑定. 只有这三种公开选项被接受;秘密和交付选项失败 审定。 表格仍提交给 subscribePath: 此整合没有 执行订阅交付或禁用窗体。 消费者必须提供 Turnstile 被保护的端点, 或在其私人预览中保持无法发送 . 每个站点选择一个邮件集成. 默认 mailer 合并保留 它的全程,中间软件和运行时的安全行为.

生产模式

from 对 replyTo。 。 。 . 一个常见的模式是 fromAddress: '[email protected]' 配对 replyTo: '[email protected]'编辑 from 住在你用 Cloudflare Email Sending(通常为 mail. 子域 ; replyTo 在真正的人类收件箱读取器的分数可以回信. replyTo 也是每个消息覆盖 sendTransactional 和每个现场 SiteMailerConfig (真实模式,自0.4.0起).

别烤回扣 fromAddress。 。 。 . 计划需要有效的电子邮件( Namez.string().email()和船舶没有默认,这是故意的。 消费者的后退就像 process.env.MAILER_FROM_ADDRESS ?? '[email protected]' 是一个脚枪: 如果在部署时缺少了 env var , 返回域可能没有通过 Cloudflare 电子邮件发送验证, 每一份发送返回 unauthorized_sender,排队重复,直到预算杀死消息。 失败了在建造/部署 当内脏不见了 —— 计划不能赶上你的后退.

秘密会按要求解决的. 捆绑 TURNSTILE_SECRET_KEY 财务报告和审定财务报表 MAILER_SIGNING_SECRET 在工人号上。 普通工人秘密和秘密存储库 绑定都支持; 密钥存储绑定用 Aync 读取 .get() 并每个隔离处缓存。 缺少或空生产绑定在503个之前返回 订阅者写作. Build-time 字面选项在本地主机外被忽略 .

输入什么

路线 :

  • POST /api/newsletter/subscribe - 受转弯保护的订阅
  • GET /api/newsletter/confirm?token=... - 双重选择加入确认
  • GET /api/newsletter/unsubscribe?token=... ——一击取消订阅
  • GET/POST /email/preferences?token=... ——首选中心页
  • POST /api/email/webhook - ESP 网页接收器(交付、回弹、投诉),可选的HMAC签名验证
  • GET /api/email/open/:trackingId ——开放跟踪像素
  • GET /api/email/click/:trackingId - 点击跟踪方向

组件 :

  • <SubscribeForm /> - 带有Turnstile的通讯注册表
  • <PreferenceCenter /> - 专题订阅管理

D1 表格(前缀) gl_(中文(简体) )

  • gl_subscribers ——订阅者记录(电子邮件,名称,状态,议题,已确认 at)
  • gl_email_sends — 发送日志( 状态: 队列已到 ) – 已发送 – 已发送 – 已打开 – 已点击 )

装订

[[d1_databases]]
binding = "SITE_DB"
database_id = "..."

[[queues.producers]]
binding = "EMAIL_QUEUE"
queue = "email-sends"

[[queues.consumers]]
queue = "email-sends"
max_batch_size = 10

[[analytics_engine_datasets]]
binding = "ANALYTICS"
dataset = "your_analytics_dataset"

[[secrets_store_secrets]]
binding = "TURNSTILE_SECRET_KEY"
store_id = "..."
secret_name = "your-turnstile-secret"

[[secrets_store_secrets]]
binding = "MAILER_SIGNING_SECRET"
store_id = "..."
secret_name = "your-mailer-signing-secret"

电子邮件发送流程

  1. 消费者电话 sendTransactional(), (中文(简体) ), sendCampaign(),或 sendDigest() ~ 信息排队
  2. 通过 Cloudflare Email 发送 与可重试失败的重试
  3. 更新状况 gl_email_sends: 队列已出 出 出 出/出
  4. 进一步打开/点击跟踪更新状态

密钥模式

  • 虚拟模块 : virtual:growth-labs/mailer/config
  • 运行时间绑定 : import { env } from 'cloudflare:workers'
  • 情况从未降级(已发到)
  • 每封邮件( RFC 8058) 上列表- 取消订阅页眉
  • 在订阅端点上转动( + IP 速率限制为备份)
  • 为可观察性而登录的提供者故障
  • WAE事件通过配置的Analytics引擎捆绑——火与遗忘,非阻塞,并兼容其装订物 writeDataPoint() 返回时 void
  • Cloudflare 电子邮件发送使用当前结构 html 有效载荷和远期 replyTo 加自定义标题到绑定
  • .astro 组件文件为源文件, 未编译

分析事件

何时 analyticsEnabled 真实和配置 analyticsBinding 数据点 newsletter_subscribed, (中文(简体) ), newsletter_confirmed, (中文(简体) ), newsletter_unsubscribed, (中文(简体) ), newsletter_opened, (中文(简体) ), newsletter_clicked, (中文(简体) ), newsletter_delivered, (中文(简体) ), newsletter_bounced, (中文(简体) ), newsletter_complained, (中文(简体) ), newsletter_sent,以及 newsletter_send_failed。 。 。 .

版本与发布记录

@growth-labs/mailer 共发布 27 个版本,首次发布于 2026/04/13;过去 12 个月发布了 27 个版本。

版本发布日期距今
0.8.2latest2026/10/2720 天前
0.8.12026/10/2721 天前
0.8.02026/10/2621 天前
0.7.02026/10/2523 天前
0.6.52026/10/2424 天前
0.6.42026/10/2424 天前

关于 @growth-labs/mailer 的常见问题

@growth-labs/mailer 是什么?

基于队列的Astro + Cloudflare 电子邮件发送引擎. 通讯订阅有双选入,活动发送,开放/点击跟踪,不订阅管理. 使用 Cloudflare Quees 来进行Aync送出.

如何安装 @growth-labs/mailer?

在项目目录运行 npm install @growth-labs/mailer,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:astro(^6.1.10 || ^7.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@growth-labs/mailer 支持 TypeScript 吗?

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

@growth-labs/mailer 支持 ESM 还是 CommonJS?

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

@growth-labs/mailer 可以商用吗?

@growth-labs/mailer 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@growth-labs/mailer 的下载量有多少?

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

@growth-labs/mailer 还在维护吗?

最新版本 0.8.2 发布于 2026/10/27(20 天前);至今共发布 27 个版本,其中过去 12 个月发布了 27 个;首次发布于 2026/04/13。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。