最近我把团队内部的邮件发送能力整体重做了一遍做了一个可自托管的邮件发送 API 服务定位就是某商业邮件发送服务的替代品。这个项目源于一个很实际的需求我们不想在每次发通知邮件时都去依赖外部付费服务既不想让业务数据在别人那里多留一份也不想被单封邮件的单价卡脖子。所以干脆照着那些成熟产品的思路自己造了一个核心链路从 API 入口到模板渲染、发送队列、退信处理、Webhook 回调都做了一遍。这篇文章把过程中的关键设计、代码实现和踩坑记录都整理出来给有同样需求、正在纠结“要不要自己做”的团队一点参考。阅读本文需要你对 HTTP API、消息队列和邮件基础协议有一点了解但我会把涉及邮件身份验证和送达率的部分尽量讲得直白适合后端开发者、全栈工程师和独立开发者。1. 邮件 API 服务替代品这事到底值不值得做1.1 这类服务到底解决了什么问题先聊一个基础问题邮件发送 API 服务本质上做什么它把“发一封邮件”这件事封装成一个 HTTP 接口业务方不用关心 SMTP 服务器怎么连、连接池怎么管、退信怎么解析只需要提交一个 JSON包含收件人、标题、正文或模板 ID剩下的由服务来搞。听起来很简单但真实业务里邮件发送的复杂度远超想象。一次发送可能要在几秒内完成送达率需要跟踪垃圾邮件过滤规则需要适配发件人身份需要验证失败还需要重试。把这些能力沉淀到一个统一服务里业务方就能彻底摆脱发信细节。我们决定做替代品主要原因是三个成本、数据主权和定制空间。商业服务的付费模式通常是按量计费邮件数量上来之后是一笔不容忽视的固定支出。更重要的是很多业务场景对收件人邮箱地址、发送内容有保密要求不希望这些数据经过第三方。还有一类需求是自定义回报率、自定义退信分类规则、自定义域名验证体系这些在封闭平台里很难完全满足。自己做一个内部服务本质上是用开发成本换取长期成本和可控性。1.2 替代方案的适用场景和边界不是所有团队都适合自研邮件服务。我建议你把下面这张适用清单和排除清单过一遍。如果你的团队月发送量在几万封以下、业务不复杂直接使用商业化服务或者云厂商的邮件接口通常更划算。如果发送量上升到了几十万封或者对数据链路有合规要求自研才进入讨论范围。自研的边界也很明确它并不负责解决“IP 信誉”问题不负责优化邮箱服务商的垃圾邮件判定策略也不负责把退信率从 5% 压到 0.1%——这些更多取决于你的发送内容质量和域名历史。我这次项目的定位就是“中间件”对外提供和商业服务高度接近的 API 体验对内对接我们自己维护的邮件通道。这样的好处是业务方不需要感知底层切换如果某个通道的 IP 被限制我只需要在服务内部调整通道权重业务方代码一行不用动。判断维度用商业服务自己做替代品前期投入低注册即用高需要设计和维护单封成本随量级增加取决于通道资源数据掌控第三方留存完全自控定制能力受平台限制可随需定制送达率保障依托大平台信誉依赖自身域名和通道质量2. 技术选型与架构设计把发送链路拆成四段2.1 为什么说消息队列是这块的命根子做邮件发送服务最容易犯的错误是把发送逻辑直接写在 API 请求里收到请求后同步连接 SMTP 服务器发完再返回响应。这在小流量阶段看起来没问题但一旦邮件服务方响应变慢整个 API 服务就跟着卡住。你想想一封邮件可能需要几百毫秒到几秒而 SMTP 超时可能长达几十秒如果所有请求都同步发信QPS 稍微上来连接就会大量堆积。所以我设计的第一原则就是API 只负责收单和校验真正的发送动作全部交给异步队列。消息队列选型上我们选择了基于 Redis 的轻量队列理由很朴素团队里已经有 Redis 在跑不需要再引入一套 Kafka 或者 RabbitMQ 来增加运维成本。邮件发送任务的实时性要求不算极高分钟级延迟可以接受Redis 的简单可靠已经足够。队列抽象出两个角色生产者和消费者。API 服务是生产者发送 Worker 是消费者。多个 Worker 可以水平扩展同时干活某个 Worker 挂掉之后队列里的任务不会丢因为还有重试机制。架构上我把整个系统拆成四段接入层、校验层、发送层、反馈层。接入层就是 HTTP API负责鉴权和参数接收校验层负责校验邮箱格式、检查发送频率限制、清洗数据发送层从队列里取出消息执行模板渲染并完成 SMTP 协议发送反馈层通过解析退信邮件、读取 SMTP 回应状态或者用户手动标记把最终投递状态写回数据库再触发 Webhook。层与层之间只通过队列和数据库状态交互互不阻塞。2.2 数据模型发信任务的状态机设计邮件任务最好用一个独立的状态字段来管理而不是只在日志里打点。我设计了几个状态pending、queued、sending、sent、failed、bounced、complained。API 接收任务后置为queuedWorker 开始处理时置为sendingSMTP 服务器返回 250 表示发送成功置为sent超时或连接失败置为failed后续退信回调到来时再从sent改为bounced。状态机的好处是所有上游业务都可以通过查询任务 ID 获取实时状态不需要自己猜。任务表的主要字段包括任务 ID、发件人、收件人、标题、正文或模板 ID、模板参数、优先级、状态、重试次数、创建时间、更新时间、最后错误信息。优先级字段我强烈建议保留因为邮件服务通常会同时处理系统通知类邮件和营销类邮件重要告警邮件需要插队。实现方式很简单队列框架都支持优先级设置 Priority 后 Redis 会根据分数排序不用自己写调度算法。3. 核心模块实现从 API 到模板渲染、退信处理3.1 一个最小可用的发送 API 长什么样先上代码我用 Node.js 风格写但思路和语言无关。核心接口是POST /v1/emails请求体携带from、to、subject以及content或templateId。收到请求后第一步是参数校验第二步是速率限制检查第三步是生成任务 ID 并写入队列最后返回 202 Accepted表示任务已经受理但不保证马上发送成功。这种异步模式是邮件 API 的主流做法因为发送结果本身就需要时间才能确定同步等待太久而且容易超时。// routes/emails.js const { addEmailTask } require(../queue); const { validateEmailPayload } require(../validation); const { checkRateLimit } require(../ratelimit); app.post(/v1/emails, async (req, res) { const payload req.body; const validationError validateEmailPayload(payload); if (validationError) { return res.status(400).json({ error: validationError }); } const rateLimitError await checkRateLimit(payload.from, payload.to); if (rateLimitError) { return res.status(429).json({ error: rateLimitError }); } const taskId await addEmailTask({ from: payload.from, to: payload.to, subject: payload.subject, templateId: payload.templateId, data: payload.data, }); res.status(202).json({ id: taskId, status: queued }); });addEmailTask内部其实只是把任务塞进队列。这里有一个容易被忽略的细节任务 ID 应该在入队之前生成这样即使入队失败也可以返回明确的错误而不是让业务方拿着一个无效 ID。我用的 ID 是带时间前缀的随机字符串比如20250101xxxxxxxx方便排查时直接根据时间范围定位日志。3.2 参数校验不光是格式问题邮件参数校验比看起来要复杂不只检查邮箱格式。格式正则总有漏网之鱼比如ab在一些系统里会被当成合法地址但实际发送时大概率失败。我选择把校验拆成两层第一层用正则检查基本格式第二层调用收件人域名的 MX 记录查询接口判断这个域名是否真的有邮件服务器。后者是异步操作不能阻塞主流程所以我把它放在校验层后面异步执行校验失败的任务直接标记failed并写入原因。模板参数校验也值得注意。如果你支持模板功能业务方可能传入一个对象作为模板变量。如果模板里用到了{{name}}而业务方没传name渲染引擎不会报错只会输出空字符串最终产生一封不完整的邮件。这种情况很难被业务方发现所以我要求每个模板声明必填参数渲染之前做一次校验。简单做法是在模板配置里加一个requiredFields数组渲染时逐个检查。3.3 队列 Worker 与指数退避重试Worker 的实现核心是消费队列任务并执行发送。如果发送失败最简单的处理方式是直接重试但必须设置退避策略。我采用的是指数退避第一次重试等 1 秒第二次等 5 秒第三次等 25 秒随着次数增加间隔指数增长。原因很简单邮件服务方或者网络故障往往不是瞬间恢复的密集重试只会加重对方压力也会让自己更快被限流。// worker.js const { Worker } require(some-queue-sdk); const { renderTemplate } require(./template); const { sendMail } require(./mailer); const worker new Worker(email-task, async (job) { const { from, to, subject, templateId, data } job.data; const html await renderTemplate(templateId, data); try { await sendMail({ from, to, subject, html, messageId: job.id, }); return { status: sent }; } catch (err) { console.error(Task ${job.id} failed:, err); throw err; } }, { attempts: 5, backoff: { type: exponential, delay: 1000 }, });重试时还有一件事必须处理幂等性。如果第一次发送其实已经成功但响应超时导致 Worker 误判失败重试就会造成重复发送。收件人收到两封一样的邮件体验很糟。解决办法是在邮件头自定义一个X-Mail-Task-ID字段值为任务 ID收件方服务器一般不会因为自定义头拒信但我们需要在业务层面保证同一个任务 ID 不会在短时间窗口内被重复提交。实现时每次任务被 Worker 消费前查一下 Redis 中的发送记录如果状态已经是sent且发送时间在几十秒内就直接跳过。4. 上线前后最容易翻车的地方域名验证与送达率4.1 SPF、DKIM、DMARC 一个都不能少邮件服务最怕的是发出去就被丢进垃圾箱而垃圾箱判定很大一部分取决于发件方域名是否验证过三个东西SPF、DKIM、DMARC。SPF 声明哪些 IP 允许代表你的域名发信DKIM 用数字签名保证邮件正文没有被篡改DMARC 告诉收件方如果前两者校验失败应该怎么做。这三个配置在 DNS 层面展开我简单展开一下。SPF 是 TXT 记录内容类似vspf1 include:spf.example.com ~all表示只允许指定的发送服务器使用该域名。配置好之后还需要确保实际发送邮件的服务器 IP 确实在这个列表里否则就是搬石头砸自己的脚。DKIM 由邮件服务器生成一对密钥公钥存放在 DNS 的 TXT 记录里私钥保存在发送服务中。发送时用私钥对邮件头做签名收件方用公钥验证。DMARC 记录则类似vDMARC1; pnone; ruamailto:xxxxexample.com刚开始建议先设为pnone观察一段时间再逐步提升到 quarantine 或 reject。我踩过最大的坑是SPF 配置了DKIM 也配置了但收件方解析 DKIM 时找不到公钥。原因是生成密钥的时候DNS 记录的选择器名称写错了。不同的邮件服务器可能用不同的选择器有的用default有的用k1配置时必须对齐发送服务生成公钥时使用的选择器。另外DKIM 签名中d字段对应的域名必须和发件人域名一致不一致直接验证失败。4.2 退信和垃圾箱的排查思路上线后最头疼的问题是“邮件显示发送成功但收件人没收到”。这里要分清两种反馈一种是 SMTP 服务器在交易过程中明确返回 550 之类的错误码说明收件人地址不存在或者被拒收这种情况 Worker 会捕获并标记失败另一种是服务器返回 250 接受了邮件但邮件最终被收件方投进了垃圾箱甚至静默丢弃。后面这种没有明确错误信息只能通过收件方提供的反馈或投诉数据来间接判断。排查垃圾箱问题时我一般按四步走先检查内容的文本占比纯图片或超链接过多的邮件容易被命中垃圾规则再检查发信频率同一个域名突然从每天几百封涨到几万封会被收件方怀疑异常然后检查域名预热情况新域名直接大规模发送几乎必进垃圾箱最后才会考虑 IP 信誉问题。我们自己做的时候经常把测试邮件同时发到几个主流邮箱的测试地址观察它们分别落在收件箱还是垃圾箱。4.3 打开率和点击率的取舍跟踪邮件是否被打开、链接是否被点击是很多业务的硬需求。实现方式不外乎内嵌一个不可见的 1x1 像素图片在图片加载时记录事件的回调地址点击链接则通过把邮件里的链接替换成带重定向参数的地址。但打开率跟踪有代价不少邮件客户端默认会拦截远程图片一旦拦截打开事件就不会被上报导致数据偏低。如果邮件是纯文本形式则根本无从跟踪。所以我会建议把打开率、点击率跟踪作为可选开关业务方明确需要时才开启而不是默认全开。实现时邮件 HTML 中的图片地址要带任务 ID 和收件人哈希例如https://track.example.com/open?taskxxxuseryyy。为了防止恶意刷量user 参数不要直接放邮箱地址而是放邮箱地址的 HMAC 签名。收件人打开邮件加载图片时服务端校验签名通过后记录事件。点击链接同理替换成/click?targetbase64Urltaskxxxuseryyy重定向之前先记录点击事件。需要注意的是重定向响应必须是 302不能让前端 JS 执行跳转否则部分邮件客户端会拦截。5. 日志、监控与后续扩展5.1 把发送日志变成排查故障的第一抓手没有日志的邮件服务等于闭眼开车。每次发送任务的状态变化都要落日志而且要带上任务 ID、发件人、收件人、模板 ID、通道信息、耗时、错误码。这些日志平时看起来没什么用真正出问题的时候却能让你的排查时间从两小时压缩到两分钟。日志设计我建议全链路采用同一个traceId从 API 接受请求开始生成经过队列、Worker 重试、Webhook 挂接全程携带方便把一次发送的所有记录串联起来。另外日志不能只写在本地文件里还要同步到中心化日志系统。我自己的经验是线上服务器经常是多个实例并行处理队列任务如果日志散落各机排查时要手工拼上下文非常痛苦。至少要做到按任务 ID 检索日志并且保留原始请求参数和渲染后的邮件内容摘要。保存邮件内容摘要时要注意脱敏如果收件人邮箱和邮件主题属于敏感数据日志里要做掩码处理避免泄露。5.2 Webhook 订阅让业务方感知送达状态业务方通过 API 提交任务往往希望知道邮件最终有没有成功送达因此 Webhook 是替代品必须具备的能力。实现上我提供/v1/webhooks接口业务方可以注册回调 URL 和订阅的事件类型。事件类型至少包含email.sent、email.delivered、email.bounced、email.complained。发送 Worker 完成状态更新后会往 Webhook 派发队列里推一条事件消息后台消费者负责按订阅配置推送到业务方服务器并记录成功的送达和失败的推送。Webhook 推送需要设计重试因为业务方接口可能短暂不可用。我的策略是每次推送最多重试 3 次间隔 30 秒如果业务方收到事件后返回 2xx则视为成功。为了不让业务方重复处理同一条事件事件内容会带上唯一事件 ID建议业务方按事件 ID 做幂等。这里有一个容易被忽略的点Webhook 的推送不能影响主流程任务的状态更新。即使事件推送失败邮件本身该发还是发不能因为回调失败就回滚状态。5.3 后续可以考虑的能力批量发送与 A/B 测试主体功能跑通以后可以继续扩展的能力有很多。批量发送是一个高频需求业务方需要向几千个用户发送同一封模板邮件。最简单的方式是支持请求体里带上收件人数组服务端自动拆成多个任务入队。但要注意每个收件人的个性化数据可能不同所以不能只传一个模板数据最好是一个收件人数组每一项都包含收件人地址和对应的模板变量。实现方式上API 收到批量请求后循环校验单个收件人数据然后批量写入任务表最后返回一个批量任务 ID业务方可以用这个 ID 查询整批任务进度。A/B 测试是营销团队的硬需求给两组用户发送不同版本的邮件然后比较打开率或点击率。如果要在替代品里实现需要支持在一个批量任务中配置多个模板版本和分组规则样本分配可以由服务端完成也可以由业务方在请求里指定变体 ID。这个功能我目前只做到了替身层还没有完全做成分组调度但数据结构已经预留了变体字段。如果你正在面向多团队提供服务早期设计时建议把这些字段预留出来避免后期返工。6. 个人体会与两个补救技巧这个项目从立项到能够稳定每天发送几万封邮件前后大概花了三周。真正难的不是 API 和队列而是把邮件送达率做到符合预期。很多东西看着简单实际配置一步错后面全是坑。比如 DNS 记录生效需要时间SPF 和 DKIM 配置完不能用立刻判断至少等几个小时再用在线工具检查验证结果。再比如发送频率控制一开始我没有针对同一发件人做并发限制结果有一次批量任务同时把几百封邮件推给同一个收件方域名触发了对方限流后面几百封全部失败。最后分享一个补救技巧如果你已经用新域名发了一批邮件发现大量进入垃圾箱最有效的救法不是立刻修改邮件内容而是先停掉批量发送把域名冷却两三天再从小流量开始逐步提升。什么叫小流量每天几十封然后观察送达情况确认没问题再慢慢翻倍。这个过程叫域名预热市面上也有第三方平台可以做但原理就是这样离不开耐心和缓慢增长。还有一个小的实操细节在开发环境调试时可以用一个假的 SMTP 调试服务器来接收邮件避免把测试邮件发到真实收件人邮箱。我本地一直开着这样一个调试服务所有开发环境的邮件全部打进去然后直接在网页里查看邮件渲染效果。这样既能快速调样式又不会干扰真实发送数据。等代码通过代码评审后再用测试环境发送到白名单测试邮箱验证真实链路。这一套流程下来新同事接手维护这个项目也能很快上手。