listmonk 如何接入 Azure Communication ServicesEvent Grid 交付报告转为弹跳记录【免费下载链接】listmonkHigh performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.项目地址: https://gitcode.com/GitHub_Trending/li/listmonk如果你的邮件营销发送量走 Azure Communication ServicesACSEmail投递失败bounced、suppressed 等不会自动进入 listmonk 的弹跳统计。listmonk 提供了一条现成的集成路径把 ACS 通过 Azure Event Grid 发出的 Email Delivery Report 事件推送到 listmonk 的弹跳 Webhook由 listmonk 自动解析成 hard / soft / complaint 弹跳记录。本文基于 Bounce processing 文档 中 Azure Communication Services (ACS) 一节完成从 listmonk 设置到 Event Grid 订阅配置的完整接入。前提listmonk 已部署并可访问管理后台且发送通道使用 ACS Email。在 listmonk 侧开启弹跳处理与 ACS 接收进入 Settings → Bounces配置Enable bounce processing:Enabled只有开启后 POP3 扫描与弹跳 API 才可用Enable bounce webhooks:EnabledEnable Azure ACS:Enabled可选填写Azure Event Grid Shared Secret可选如果你希望 listmonk 从自定义请求头读取密钥填写Azure Shared Secret Header Name默认头名为X-Listmonk-Webhook-Secret进入 Settings → SMTP点击Azure ACS快速预设quick preset填入 SMTP 默认值再补充你的账号认证信息。关于共享密钥的验证逻辑在 internal/bounce/webhooks/azure.go 中verifyAuth会依次比较请求 URL 中code查询参数和配置头默认X-Listmonk-Webhook-Secret中的值与本地shared_secret。注意如果 listmonk 未配置 shared secret接口会直接放行所有 Webhook 请求生产环境建议配置密钥。创建 Azure Event Grid 订阅在 Azure 侧为你的 ACS Email 事件创建 Event Grid subscription关键参数Endpoint type:Web HookEndpoint URL:https://listmonk.yoursite.com/webhooks/service/azure其中listmonk.yoursite.com替换为你 listmonk 实例对外可访问的域名。认证二选一查询参数认证Endpoint URL 后追加?codeyour-shared-secretyour-shared-secret替换为你在 listmonk Bounces 设置里填入的同一个密钥请求头认证让 Event Grid 把同一个密钥放进 listmonk 中配置的头名称默认X-Listmonk-Webhook-Secret。两个细节创建订阅时 Event Grid 会发送一次 subscription validation 事件listmonk 的ProcessSubscription会自动返回对应的validationResponse完成握手无需人工处理事件订阅类型选Microsoft.Communication.EmailDeliveryReportReceived这是 listmonk 唯一处理的投递报告事件类型其他类型的事件会被直接忽略。事件如何被转换为弹跳记录listmonk 收到事件后按事件中的status与deliveryStatusDetails.statusMessage做映射见 azure.go 中的 mapAzureStatusACS 事件状态转换结果bounced、suppressedhard 弹跳failed且详情中含5.x.xSMTP 状态码hard 弹跳failed且详情中含4.x.x状态码或 mailbox full、temporar、timeout、rate limit、throttle 等字样soft 弹跳failed且详情中含 invalid、does not exist、unknown user、domain 等字样hard 弹跳filteredspam、quarantined且详情中含 spam complaint、complaint、abusecomplaintfilteredspam、quarantined无上述字样soft 弹跳其他状态如正常投递成功不产生弹跳记录事件中的recipient会作为弹跳记录的邮箱地址原始事件数据保存在弹跳的 meta 字段中source 标记为azure。验证接入结果按文档要求发送测试邮件向一个可触发投递失败或退订反馈的地址然后在 listmonk 的弹跳页面确认出现对应记录。也可以走 API 核对curl -u username:password http://localhost:9000/api/bounces或直接查库文档给出的查询仅截取必要列SELECT bounces.created_at, bounces.subscriber_id, subscribers.uuid AS subscriber_uuid, subscribers.email AS email FROM bounces LEFT JOIN subscribers ON (subscribers.id bounces.subscriber_id) ORDER BY bounces.created_at DESC LIMIT 1000;记录是否生成、类型是否符合预期以 Bounces 页面与上述查询的实际输出为准。边界与限制该接入只处理Microsoft.Communication.EmailDeliveryReportReceived事件如果你在 Event Grid 里订阅了 ACS 的其他事件类型listmonk 会忽略它们。文档对弹跳后续动作如 soft/hard 达到次数后 Blocklist的说明在 Bounces 设置的 action 配置中ACS 接入本身不改变这些动作的触发逻辑。若订阅创建后 Event Grid 一直无法完成校验握手优先核对 Endpoint URL 是否对外可访问、code参数或请求头中的密钥与 listmonk 侧配置是否一致。更多背景与外部服务商弹跳 Webhook 端点对照可继续参考 docs/docs/content/bounces.md 中的 External webhooks 一节。【免费下载链接】listmonkHigh performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.项目地址: https://gitcode.com/GitHub_Trending/li/listmonk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考