简介这是一份阿里云邮件推送服务的官方SDK使用手册以PDF格式发布面向需要在业务系统中集成邮件发送、接收与管理功能的Java/PHP开发者尤其适合初次接触阿里云邮件推送的团队或个人。压缩包内共1个PDF文件整体大小约440KB内容覆盖Access Key创建、Java SDK与PHP SDK的安装方式、环境要求、Maven依赖配置以及SingleSendMail等接口的调用示例结构清晰便于按教程段落快速查阅。已有209人学习下载可视为入门并落地邮件推送功能的实用参考资料。读者到手后可直接对照手册完成SDK环境搭建并基于示例代码将参数替换为自己的Access Key、发信地址和收件人快速实现简单发信能力减少反复查阅官方文档的成本。1. 从阿里云邮件推送服务 SDK 手册看开发前要确认的三件事拿到这份阿里云邮件推送服务 SDK 手册时我通常不会从第一个章节往后读而是先翻到初始化示例确认三件事AccessKey 类型、发信域名状态、接口版本。这三件事里最容易让人空转的是发信域名代码写得再完整只要域名没有在控制台完成 SPF 或 DKIM 验证邮件就发不出去或者全部进垃圾箱。另一个容易踩的是接口版本邮件推送服务的 API 版本是 2015-11-23而很多从其他云产品转过来的开发者会误用新版的版本号。下面只讲按这份手册从零调通、再放到生产环境这条路径适合给业务系统做通知、验证码、账单邮件的后端开发。2. 用 Maven 配置阿里云仓库并初始化邮件推送服务 SDK2.1 在 settings.xml 里配置阿里云公共仓库Java 项目第一次引入邮件推送服务 SDK 时卡住的地方往往不是代码而是依赖下载。内网构建如果只配了中央仓库通常会有不少依赖解析超时尤其是 aliyun-java-sdk-core 这种带一堆 httpclient、json 传递依赖的包。常见做法是把 Maven 的 settings.xml 加一个 mirror指向阿里云公共仓库。mirror idaliyun-public/id mirrorOf*/mirrorOf namealiyun public mirror/name urlhttps://maven.aliyun.com/repository/public/url /mirror这段 XML 里 mirrorOf 的写法作用域是整个构建。把 mirrorOf 写成*意味着所有仓库请求都走阿里云适合没有私服的小团队如果我同时要拉公司内部构件就会改成external:*避免把自己的私服也镜像掉。URL 用的是/repository/public它聚合了 central 和 jcenter 的内容DTO 类和核心包都能在上面找到。改完后不需要重新导入整个项目只要在 IDEA 里刷新 Maven 面板或者命令行执行mvn dependency:resolve即可。2.2 引入依赖并区别 RPC 旧版与新版专用 Client邮件推送服务 SDK 手册里通常存在两套用法一套是基于 aliyun-java-sdk-core 的 RPC 风格请求对象带着 set 方法调client.getAcsResponse发出去另一套是近年推广的以产品命名的新版 Client参数更贴近 REST。老风格的好处是网上资料多错误信息直观适合快速跑通新风格把 Endpoint 和签名收敛在一个 builder 里适合新项目长期维护。我这里用老风格做示例因为它的类名和参数在手册里最容易被搜到。dependency groupIdcom.aliyun/groupId artifactIdaliyun-java-sdk-core/artifactId version${aliyun.core.version}/version /dependency dependency groupIdcom.aliyun/groupId artifactIdaliyun-java-sdk-dm/artifactId version${aliyun.dm.version}/version /dependency版本号我习惯放在 properties 里统一定义正式填写时以你手里的 SDK 手册标注为准不要直接照抄网上的数字。两个依赖缺一不可core 提供签名、HTTP 传输和 CommonRequestdm 提供邮件推送服务相关的请求对象。如果只引入 dm 而漏掉 core编译期通常不报错运行期会一直报 ClassNotFoundException。初始化客户端的代码很短String regionId cn-hangzhou; DefaultProfile profile DefaultProfile.getProfile( regionId, accessKeyId, accessKeySecret); IAcsClient client new DefaultAcsClient(profile);regionId 多数情况下填cn-hangzhou但如果控制台里看到资源属于其他地域或者使用的是国际站资源要改成对应地域否则后端会提示资源不存在。AccessKey 建议用 RAM 子账号而不是主账号子账号只需要AliyunDirectMailFullAccess权限避免密钥泄露时整个账号被拖走。参数作用取值建议regionId决定 Endpoint 与资源归属与控制台一致accessKeyId鉴权身份RAM 子账号accessKeySecret签名密钥不要写进代码仓库2.3 用一次只读请求验证初始化和签名链路初始化完成后不要急着发信先调一个只读接口验证签名链路。这样做的原因是发送接口一旦带着错误凭据跑起来可能已经消耗了配额而查询接口可以反复调。CommonRequest request new CommonRequest(); request.setDomain(dm.aliyuncs.com); request.setVersion(2015-11-23); request.setAction(DescAccountSummary); request.setMethod(MethodType.POST); CommonResponse response client.getCommonResponse(request); System.out.println(response.getData());如果你手里的 SDK 版本较新编辑器可能提示 setDomain 已废弃改成 setSysDomain 即可作用一样。这次请求不会产生任何发送只读取账号概览所以适合当初始化探针。返回的 JSON 里能看到日配额、月用量之类的信息说明签名、Endpoint、权限三条链路都通了。如果这步都过不去后面的发送代码不用看问题基本在凭据或网络环境。3. 邮件推送服务 SDK 的单发、批量发送与参数取舍3.1 先跑通单发SingleSendMailRequest 最小代码初始化探针通过后第一封测试邮件用单发接口最直接。SingleSendMailRequest 是手册里最常出现的请求对象下面的代码是我在新项目里会先跑通的最小版本。SingleSendMailRequest request new SingleSendMailRequest(); request.setAccountName(no-replyexample.com); request.setAddressType(1); request.setReplyToAddress(true); request.setToAddress(userexample.com); request.setSubject(你的登录验证码); request.setHtmlBody(p验证码1234565 分钟内有效。/p); SingleSendMailResponse response client.getAcsResponse(request); System.out.println(response.getEnvId());AccountName 必须是已经创建并通过审核的发信地址不能临时编一个。AddressType 的 0 和 1 对应不同发件展示形式0 表示直接用发信地址本身1 表示用系统生成的随机地址加上你的域名验证码场景我一般用 1退信时可以把问题邮件隔离在随机地址上。ReplyToAddress 设置为 true 后收件人点回复时信件回到发信地址如果只是通知类邮件建议设为 false减少回信堆积和后续处理成本。返回的 EnvId 是一次发送的流水号不管后面有没有开回执都应该先落库。标题和正文都有长度限制HTML 正文里不要塞 base64 图片常见做法是把图片放到 OSS 后传 URL。如果收件人客户端不支持 HTML手册里还允许填 TextBody所以事务类邮件我通常会同时提供 TextBody 和 HtmlBody。3.2 批量发送与模板的关系批量接口和单发不同不是传一个收件人列表而是先创建收件人列表和模板再提交批量任务。手册里对应的请求会要求 TemplateName 与 ReceiversName 两个参数。BatchSendMailRequest request new BatchSendMailRequest(); request.setAccountName(no-replyexample.com); request.setTemplateName(verification_code); request.setReceiversName(order_users); request.setAddressType(1); BatchSendMailResponse response client.getAcsResponse(request);批量发送失败时错误不一定立即暴露在响应里因为任务是异步的。所以调用方要保存返回的任务 ID然后通过查询接口轮询任务状态。模板里如果要用变量占位符需要与收件人列表文件里的字段名完全一致少一个空格都可能导致整批失败。这里最容易出现的误用是以为 BatchSendMail 可以像群发工具那样直接在参数里写多个收件人地址。参数单发批量收件人ToAddressReceiversName 引用的收件人列表内容Subject HtmlBody模板 TemplateName返回EnvId任务 ID适合场景验证码、触发邮件营销、账单、大批量通知3.3 退信回执与打开追踪TagName 和 ClickTrace 的用途单发请求里有两个常被忽略的参数TagName 和 ClickTrace。TagName 相当于业务标签同一类邮件打同一个标签在控制台和事件查询里就能按标签聚合ClickTrace 取 0 或 1开启后SDK 下发的内容里会嵌入追踪链可以统计打开和点击。生产环境里我一般不会把这两件事当附加功能而是把 TagName 当成业务维度的事件分区。比如周报邮件 TagName 填 weekly_report退信回调里看到这个标签就知道是哪个场景的任务。ClickTrace 开启后会影响邮件体积和隐私营销邮件适合开纯事务通知建议关掉避免收件人反感。需要说明的是事件结果不是同步返回的。SDK 手册里回执章节一般会讲事件通知的订阅方式常见做法是配置到消息服务或 HTTP 端点服务端再解析事件里的 EnvId、TagName、事件类型把结果写回任务表。这里不要用轮询去模拟事件通知轮询间隔短了会增加额外调用量间隔长了又会延迟退信处理。4. 接入业务系统时如何给邮件推送服务 SDK 设计限流和重试4.1 控制台额度与本地限速配合邮件推送服务在控制台上能查到的额度有两类账号每日总量和接口调用速率。前者按自然日重置后者按秒。SDK 本身不会帮你限速所以业务侧要自己挡住尖峰。我一般会先压测一轮观察返回的限流错误再把本地速率设为控制台配额 70% 左右留出给其他调用方的余量。RateLimiter limiter RateLimiter.create(20.0); // 每秒最多 20 封 ExecutorService pool Executors.newFixedThreadPool(4); for (SendTask task : tasks) { limiter.acquire(); pool.submit(() - processTask(task)); }RateLimiter 是 Guava 的令牌桶实现acquire 会阻塞当前线程直到拿到许可所以这里的 20 是全局速率。线程池 4 是为了让发信请求能并发提交弥补每次网络往返的时间。注意这两个参数不能互相替代只开线程池不限速会打爆配额只限速不开线程池则发送效率太低。实际压测时先从一个较小的速率开始比如每秒 5 封确认没有限流错误后再逐步上调直到接近阈值。4.2 重试只处理网络异常不处理业务失败邮件发送不是幂等操作重试必须谨慎。ClientException 里的错误码如果把额度用尽也拿来重试结果是每重试一次就消耗一次配额反而让限流恢复得更慢。我会区分网络类超时和控制台业务错误网络类也只允许补偿一次并且要保证任务状态没有在第一次调用时其实写入成功否则用户会收到两封。try { client.getAcsResponse(request); } catch (ClientException e) { if (e.getErrCode().contains(Timeout) || e.getErrCode().contains(Throttling)) { retrySend(request, 1); } else { recordFailure(task, e.getErrCode()); } }错误特征是否重试重试策略连接超时、读超时可重试延迟 1 秒最多 1 次请求被限流谨慎重试按响应里的 Retry-After 等待地址无效、域名未验证不重试记录并告警AccessKey 鉴权失败不重试检查凭据和权限重试代码里我建议把最大次数控制在 1 到 2 次并且每次重试前重新检查任务状态。比如第一次发送后网络超时但后端可能已经收到了请求并成功投递此时任务还停在 sending如果不做状态检查就重发用户就会收到两封验证码。生产上更保险的做法是查询接口确认没有对应 EnvId 后再补偿虽然多了一次调用但比重复投递好处理。4.3 用任务表状态机抗住批量发信批量发送不能把循环写在请求里直接跑常见做法是先建一张 mail_task 表每次发送请求都对应一行状态在 pending、sending、sent、failed、bounced 之间流转。worker 从表里捞 pending 任务捞到后立刻改成 sending。UPDATE mail_task SET status sending, worker ?, updated_at NOW() WHERE task_id ? AND status pending;这段 SQL 的关键是 WHERE 条件里带上 status pending这样两个 worker 同时捞同一行时只有一个能更新成功另一个 update 影响行数为 0就知道任务被别的节点领走了。状态变成 sending 后如果进程在回调返回前崩溃任务会一直卡住所以还要上线一个超时扫描把超过 5 分钟还停在 sending 的任务捞出来重新置为 pending。这个状态机不需要引入消息队列单库就够用量大后再把任务表挪到 MQ业务代码的发送逻辑保持不动。5. 对照 SDK 手册排查邮件推送服务的高频错误5.1 先看错误码还是先看 RequestId收到异常时我一般先看响应里的 RequestId再看错误码。理由是文档和社区里按错误码能搜到通用原因但 RequestId 才是阿里云侧排查的唯一凭证如果最终要提交工单工单里没有 RequestId对方基本没法定位。所以在 2.3 节的探针请求里我也建议把 RequestId 打出来存到日志。catch (ClientException e) { log.error(send mail failed, requestId{}, errCode{}, errMsg{}, e.getRequestId(), e.getErrCode(), e.getErrMsg()); }常见的错误大致落在四个方向域名无权使用、地址格式错误、额度超限、鉴权失败。域名无权使用对应发信地址没有完成验证或已停用地址格式错误先看收件人是不是带了中文引号或空格额度超限检查控制台配额鉴权失败重点查 RAM 子账号是否授权了AliyunDirectMailFullAccess。这几个方向的修复路径完全不同所以排查时先归类不要对着错误信息逐字猜。5.2 依赖版本与 Endpoint 不一致造成的诡异问题邮件推送服务 API 的版本字段是2015-11-23。如果参考了别的云产品示例把版本号换成了新 SDK 的日期签名串立刻就不匹配报错风格往往让人以为 AccessKey 有问题。另一个容易踩的是地域 Endpoint国内版用 dm.aliyuncs.com国际站或特定地域可能是 dm.ap-southeast-1.aliyuncs.com。手册版本页通常会列出一张 Endpoint 表我建议把地域和 Endpoint 直接写在配置类里不靠自动探测减少环境差异。# 排查 DNS 解析到的 Endpoint 是否正确 dig short dm.aliyuncs.com这条命令是很多网络排查的起点如果解析出来的 IP 不在预期网段先确认是不是本地 hosts 或公司 DNS 出了问题再回来看代码。签名和 Endpoint 混在一起报错时先解决 DNS再看版本号最后才检查 AccessKey。这个顺序能省掉大量来回试错的成本。5.3 打印 com.aliyun 日志定位签名和响应差异logger namecom.aliyun levelDEBUG/ logger nameorg.apache.http levelDEBUG/ logger nameorg.apache.http.wire levelINFO/日志级别打开后SDK 会打印实际请求的域名、HTTP 方法、响应状态码和响应体。重点看三个位置签名头是否带上 date 和 Authorization、响应体里是否出现 RequestId、请求 URL 里的 Action 参数是不是预期值。生产环境不要长期开 DEBUG因为 httpclient 的 DEBUG 会打印完整 header其中包含授权信息我一般在测试环境开确认后改回 INFO。日志位置能看到什么常见问题com.aliyunRequestId 与错误码签名或权限org.apache.http网络往返状态超时或 TLS 报错响应体配额与错误信息参数值不正确6. 用 SDK 手册之外的三个手段验证一次真实发送6.1 在 OpenAPI 调试器里先过一遍参数本地代码一旦跟手册对不上先别改代码打开控制台里的 OpenAPI 调试器选 SingleSendMail把请求参数原样填进去。调试器返回成功后再把同样参数搬回代码。这样做的好处是把问题一分为二调试器成功说明账号、域名、配额都正常剩下的差异就在代码的请求对象或签名上调试器失败则直接暴露控制台侧的问题。6.2 从收到的邮件原文验证 SPF 和 DKIM发送成功不等于送达送达不等于进收件箱。测试邮件发出后打开邮件原文找 Authentication-Results 头。如果里面的 spfpass 和 dkimpass 同时出现说明发信域名验证有效对方的反垃圾系统会给你一个较好的初始分如果两个都 fail问题通常在 DNS 记录没生效回到控制台把 DNS 记录重新验证一次。# 保存邮件原文到 eml 文件后检查认证结果 grep -i authentication-results /tmp/mail.eml这一步比看发送成功日志更接近真实链路也是排查发送成功但收不到、或者进垃圾箱最直接的手段。注意群发测试时不要用同一个收件地址反复打否则会被对方服务商按行为模式判定为垃圾邮件。6.3 用 RequestId 把发送事件串成一条链路测试时把响应里的 RequestId、EnvId 以及测试开始时间一起存进任务表。后面如果收到退信回调或打开事件能按 EnvId 关联到具体业务任务需要提工单时把 RequestId 和测试时间附上避免沟通时来回补信息。这个习惯在消息类系统里比任何日志框架都管用因为它给每一封邮件一个从发起到回执的完整坐标。本文还有配套的精品资源点击获取