@ 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"
电子邮件发送流程
- 消费者电话
sendTransactional(), (中文(简体) ),sendCampaign(),或sendDigest()~ 信息排队 - 通过 Cloudflare Email 发送 与可重试失败的重试
- 更新状况
gl_email_sends: 队列已出 出 出 出/出 - 进一步打开/点击跟踪更新状态
密钥模式
- 虚拟模块 :
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。 。 。 .