简介阿里云邮件推送服务SDK手册是一份面向开发者的技术文档可作为企业级邮件发送的解决方案参考帮助Java、PHP开发者快速对接阿里云邮件推送接口实现邮件发送与管理功能。资源共1个PDF文件资源包大小440KB体积轻量、便于离线查阅。手册系统讲解了Access Key的创建流程、Java SDK的两种安装方式手动导入jar包与Maven依赖配置并给出了SingleSendMail接口的完整Java示例代码覆盖发送邮件的参数设置与调用逻辑同时涉及PHP SDK的使用教程方便多语言团队按需查阅。全文以步骤化说明与代码片段为主适合从零上手的开发者对照操作也可作为项目开发时的常用API参考手册。目前已有210人学习对于需要快速集成阿里云邮件推送服务的技术人员具有实用价值。1. 阿里云邮件推送服务SDK手册它解决的从来不是“能发信”而是“稳定发信”拿到这本《阿里云邮件推送服务-SDK手册.pdf》很多人的第一反应是“邮件推送不就是调个接口吗”。但真做过营销邮件、验证码邮件、告警通知的人会明白邮件推送真正的成本不在“发出一封”而在“持续稳定地发一万封、十万封并且不被告警、不落垃圾箱、不触发限流”。这本手册讲的正是这条链路阿里云邮件推送服务DirectMail的SDK接入、发信参数、频率限制、地址验证和异常排查。适合正在接邮件通知、验证码、营销触达的Java/Python/PHP开发者也适合被邮件送达率折腾过的运维。如果你只是想发几封内部通知那SMTP直连够用但一旦涉及批量、模板、数据追踪和稳定送达SDK接入就不是可选项而是必需项。2. 接入阿里云邮件推送SDK从开通服务到拿到第一封测试邮件2.1 为什么走SDK而不是直接连SMTP邮件推送服务在阿里云控制台里开通之后你会拿到一组发信参数。常见做法是走SMTP直连端口25、465、587都开着账号密码填进去就能发。但直连有几个现实问题一是发信路由和IP信誉由服务端统一控制直连方式拿不到“高信誉IP池”的红利二是没有发送记录、打开率、点击率、退信分类这些数据三是批量发信时自己维护连接池和重试逻辑特别容易翻车。SDK的好处是你不用再关心HTTP签名、公共参数、请求重试这些琐碎事把账号和密钥传给客户端剩下的交给包去处理。阿里云邮件推送的SDK在Java、Python、PHP、Go、Node.js这些主流语言里都有手册里逐个给了依赖坐标和初始化方式。我一般在Java项目里用Maven引入在Python项目里用pip装官方包下面会按这两个场景拆开讲。2.2 在控制台先做好三个准备发信域名、发信地址、密钥接入SDK之前请务必按这个顺序操作顺序错了后期很麻烦。第一步绑定发信域名。登录阿里云邮件推送控制台进入“发信域名”页面添加你的域名例如notify.example.com。按页面提示配置三条DNS记录一是MX记录用于接收退信二是SPF记录用于声明发信服务器三是DKIM记录用于邮件签名。这三条DNS记录配置后通常要等几分钟到几小时生效别急着继续下一步。第二步创建发信地址。发信地址就是收件人看到的From地址比如no-replynotify.example.com。这里有个关键参数叫“发信类型”分为“触发式”和“批量式”。验证码、通知、告警这类实时触发的选触发式营销活动、订阅推送这类大批量投递的选批量式。两种类型对应的频率限制不同后面第4章会详细说。第三步创建AccessKey。控制台右上角头像菜单里进AccessKey管理创建一组AccessKey ID和AccessKey Secret。这个密钥要保存好SDK初始化时要用。不要把它写进代码仓库放到环境变量或配置中心。2.3 最小Java工程初始化客户端并发送第一封邮件这里以Java为例先看Maven依赖dependency groupIdcom.aliyun/groupId artifactIddm20151123/artifactId version1.0.2/version /dependency dependency groupIdcom.aliyun/groupId artifactIdtea-openapi/artifactId version0.2.5/version /dependency依赖装好后初始化客户端import com.aliyun.dm20151123.Client; import com.aliyun.teaopenapi.models.Config; public class DirectMailClient { public static Client createClient() throws Exception { Config config new Config(); config.setAccessKeyId(System.getenv(ALIBABA_CLOUD_ACCESS_KEY_ID)); config.setAccessKeySecret(System.getenv(ALIBABA_CLOUD_ACCESS_KEY_SECRET)); config.setEndpoint(dm.aliyuncs.com); return new Client(config); } }初始化配置里最关键的是endpoint。手册里写的默认接入地域是华东1杭州endpoint就是dm.aliyuncs.com。如果你开通的是新加坡或其它海外地域endpoint要对应改成dm.ap-southeast-1.aliyuncs.com这类地址否则会报InvalidEndpoint。接下来是SingleSendMail接口单发一封测试邮件import com.aliyun.dm20151123.models.SingleSendMailRequest; public class SendMailDemo { public static void main(String[] args) throws Exception { Client client DirectMailClient.createClient(); SingleSendMailRequest request new SingleSendMailRequest(); request.setAccountName(no-replynotify.example.com); request.setFromAlias(通知中心); request.setTo(receiverexample.com); request.setSubject(这是一封测试邮件); request.setTextBody(如果你看到这封邮件说明SDK已经跑通了。); request.setAddressType(1); // 1表示触发式0表示批量式 request.setReplyToAddress(false); request.setClickTrace(0); client.singleSendMail(request); System.out.println(发送成功请检查收件箱或垃圾箱); } }这段代码有四个参数需要解释清楚。accountName必须和控制台创建的发信地址完全一致大小写、域名后缀都不能错。addressType是个容易踩坑的参数1是触发式0是批量式它直接决定这条发信请求走的限流池。replyToAddress表示收件人点“回复”时回复信是发到发信地址还是放弃回复这里填false表示不接收回复。clickTrace是打开和点击追踪开关传0关闭传1开启开了之后可以在控制台看到打开率数据但邮件里会注入追踪像素某些严肃场景会介意这一点。跑完这段代码去收件箱翻一下。如果进了垃圾箱别急着改代码先看第5章的排查清单。2.4 Python版的最小实现Python工程的依赖和初始化相对简洁pip install alibabacloud_dm20151123from alibabacloud_dm20151123.client import Client from alibabacloud_dm20151123 import models as dm_models from alibabacloud_tea_openapi.models import Config import os config Config( access_key_idos.environ.get(ALIBABA_CLOUD_ACCESS_KEY_ID), access_key_secretos.environ.get(ALIBABA_CLOUD_ACCESS_KEY_SECRET), endpointdm.aliyuncs.com ) client Client(config) request dm_models.SingleSendMailRequest( account_nameno-replynotify.example.com, from_alias通知中心, toreceiverexample.com, subjectPython SDK 测试, text_body这是一封Python SDK发出的邮件, address_type1, reply_to_addressfalse, click_trace0 ) client.single_send_mail(request)Python端注意一个命名习惯问题SDK把所有请求参数都转成了下划线风格accountName变成了account_name。手册里可以对照查接口名和字段名都有对应关系表真记不住时直接翻手册的自定义字段和请求参数章节。3. 用SDK发信的最小工程单发、批量、模板三件套3.1 三套常用接口的适用边界邮件推送SDK核心接口就三个SingleSendMail单发、BatchSendMail批量发送、SendTestMail测试邮件。初看会以为批量发送就是把单发包在for循环里实际上不是这么回事。SingleSendMail适合验证码、告警通知这类每封邮件的收件人和内容都不同的场景每次请求发一封。BatchSendMail适合同一内容发给大量收件人的营销场景请求里带一个模板名称和收件人地址列表一次提交把整个列表交给服务端分发。两者的区别不只是“能不能循环调用”而是底层限流策略和计费逻辑完全分开。批量接口如果循环调单发会撞上限流还会产生大量无效请求。模板是第三个重要概念。邮件推送控制台支持创建“邮件模板”把变量抽出来比如验证码模板写“您的验证码是${code}”发送时填充变量即可。模板方式的好处是内容经过服务端审核发送稳定还能在看板里按模板维度统计送达率和打开率。对于营销和验证码场景我一般建议优先用模板少用直传textBody和htmlBody。3.2 BatchSendMail批量接口一次性发给多人from alibabacloud_dm20151123.models import BatchSendMailRequest batch_request BatchSendMailRequest( account_nameno-replynotify.example.com, template_name验证码通知模板, receivers_name用户列表-20240601, address_type1, tag_nameverification ) client.batch_send_mail(batch_request)这里有个隐藏操作receivers_name不是邮箱地址列表而是控制台“收件人列表”功能里创建的收件人列表名称列表中每个收件人都维护了邮箱、姓名、自定义字段。所以批量发送前你得先把收件人列表准备好有两种方式在控制台手工录入或者用CreateReceiver接口创建列表再用CreateReceiverDetail接口逐条添加收件人。from alibabacloud_dm20151123.models import CreateReceiverRequest, CreateReceiverDetailRequest client.create_receiver( CreateReceiverRequest( receivers_name用户列表-20240601, receivers_alias六月注册用户 ) ) detail_request CreateReceiverDetailRequest( receivers_name用户列表-20240601, detail张三,zhangsanexample.com,2024-06-01 ) client.create_receiver_detail(detail_request)detail字段的格式是“姓名,邮箱,自定义字段”用英文逗号分隔多条数据用换行符分隔一次请求最多200条。这里字段顺序是固定的如果填反了服务端不会报错但数据会错位后期查数据时才会发现问题。批量发送的返回值里有个RequestId和EnvIdEnvId是批次号后续查发送日志、退信记录都靠它。建议把EnvId和业务批次号做映射存到数据库里否则数据量大了之后根本不知道这批邮件对应哪个活动。3.3 模板发送把内容管理和发送分离邮件模板有两种类型text/html富文本模板和text/plain纯文本模板。在控制台创建模板后会得到一个模板名称和模板ID。SDK发送时模板里定义的变量要通过templateParam传入。request dm_models.SingleSendMailRequest( account_nameno-replynotify.example.com, toreceiverexample.com, subject验证码通知, template_id12345, template_param{\code\: \882301\}, address_type1, )templateParam必须传JSON字符串key和value都要是字符串不能传数字。代码里882301如果不加引号服务端在部分SDK版本里会解析失败这件事在手册的错误码章节有记录错误码是InvalidTemplateParam。用模板有个隐性收益发送内容无需每次携带完整HTML请求体小接口响应快。同时模板在控制台有审核流程审核通过后才能发送好处是内容违规的风险在发信前就被拦掉了。坏处是模板审核需要时间如果你有临时促销、运营文案连夜上线的需求模板审核周期会是阻碍这种情况建议走直传HTML的方式。3.4 三种方式怎么选一张表说清楚场景推荐接口频率限制备注登录验证码、操作通知SingleSendMail触发式日量相对高每条实时发延迟要求秒级营销邮件、订阅推送BatchSendMail批量式量大但限速严格需要先建收件人列表开发联调、验证配置SendTestMail无独立限制只发测试邮箱反复发送相似内容模板SingleSendMail同触发式模板需提前审核通过选接口时别只看功能要同时看限流。触发式邮件的单日配额通常远低于批量式但触发式没有批量级的“发送完一整批才休息”的问题。反过来营销场景如果走触发式很容易触发DayQuotaLimit错误当天就发不出去了。4. 发信参数与限流边界为什么换个参数就翻车4.1 addressType1 和 addressType0 到底改变了什么addressType是这个SDK里最容易被忽略又最要命的参数。它不只是一个标记而是决定你的请求被路由到哪套限流策略。设为1触发式时请求走触发邮件通道面向验证码、通知类邮件延迟低单条不计入批量额度。设为0批量式时请求走批量投递通道面向营销邮件服务端会做更严格的频控比如同一收件人一天最多收到多少封批量邮件、同一发信地址每小时最多批量请求多少批次。实际工作中最常见的翻车场景验证码服务把addressType传成0结果高并发时段大量请求被限流用户收不到验证码另一个团队做营销推送把addressType传成1结果下午3点发了一波5000封直接撞上触发式日限额晚上7点的第二波全部失败。手册中的限流参数表要重点看这几个维度单日总量、单小时速率、单收件人频次。在控制台的“发信域名”详情页里能看到当前账号的配额使用情况这个页面建议加入日常巡检清单。4.2 发信域名的三个关键配置MX、SPF、DKIM发信不成功或者频繁进垃圾箱八成是DNS记录没配全或者配错了。整理一下这三条记录的用途MX记录负责接收退信。如果MX缺失邮件服务端无法把投递失败的回执发回来你永远不知道有多少邮件没送到。排查退信时控制台里只会显示“未知退信原因”整条链路就断了。SPF记录声明“我有权使用这个域名发信”。没有SPF收件方会把你的邮件和伪造邮件混在一起处理进垃圾箱的概率大幅上升。SPF格式大致是vspf1 include:spf.aliyun.com -all具体值以控制台给出的为准。DKIM记录给邮件做签名验证。没有DKIMGmail、Outlook这类收件方对邮件的信任度会降低长时间大范围进垃圾箱不奇怪。这三条记录配置完成后用nslookup -typeTXT notify.example.com或dig MX notify.example.com检查。注意TXT记录可能有多条别只凭一条判断。4.3 发信地址与ReplyTo的联动关系发信地址在控制台创建时可以设置“回复邮件地址”。这个地址的作用是当收件人点击“回复”时回复信投递到哪里。SingleSendMailRequest里的replyToAddress参数取值true或false。传true且发信地址开启了回复收取收件人的回复才能正常回来传false回复信会被丢弃。很多团队测试时发现“收不到客户回复”查了半天不是网络问题而是这里传了false。这个参数和发信地址控制台的设置是“与”的关系两头都得配好。如果你做的是系统通知类邮件不需要收回复建议统一传false能省掉反垃圾策略把回复信识别为异常流量的麻烦。4.4 频率限制的实际观测手段阿里云邮件推送服务的限流不是SDK包的逻辑而是服务端策略。你在本地改循环次数、加线程池不会绕过它。如何知道自己的账号有没有撞限流观察返回错误码DayQuotaLimit单日额度用尽HourQuotaLimit单小时额度用尽ReceiverFrequencyLimit超出同一收件人接收频率限制。这些错误码手册的“错误码参考”一节都有列表建议把所有限流错误码摘出来在代码里做告警映射。比如捕捉到DayQuotaLimit就发钉钉通知让值班同学知道明天没法发营销邮件了。另一个观测维度是发送记录。控制台“发送记录”可以按发信地址、收件人、日期筛选能看到每封邮件的状态是“成功”“失败”还是“退信”。更细的数据通过QueryMailDetailByParam接口拉取这个接口返回的信息包含投递时间、收件方服务器返回信息连“收件人已读”这种事件都能追踪前提是打开了clickTrace。5. 阿里云邮件推送常见坑与排查发不出、进垃圾箱、报错4015.1 报错InvalidAccessKeyId密钥和端点不匹配现象SDK初始化时报InvalidAccessKeyId或SignatureDoesNotMatch代码逻辑看起来没问题密钥也是新生成复制的。原因最常见的原因不是密钥错了而是endpoint指向的地域和AccessKey所属账号不匹配。比如AccessKey是主账号的但endpoint写成了另一个地域或者AccessKey复制时多了一个空格、少了一个字符。解决重新核对AccessKey ID和Secret建议直接复制环境变量里的值不要手敲。然后确认endpoint与开通邮件推送服务的地域一致。如果是RAM子账号的Key还要检查该子账号是否被授权了AliyunDirectMailFullAccess权限策略。提示控制台生成的AccessKey有且仅有一次完整显示机会关掉页面之后就看不到Secret了。遗失后只能在AccessKey管理里删除重建别在代码里打日志找历史。5.2 发信成功却收不到垃圾箱和SPF缺失现象调用接口返回成功收件人邮箱里找不到邮件翻垃圾箱也没有。原因有几种可能。第一种收件方服务器把你发的信判定为垃圾或直接静默丢弃常见于SPF和DKIM记录缺失第二种测试用的是QQ邮箱或网易邮箱这类邮箱对陌生域名的信任度本就低第一封测试信往往会进垃圾箱第三种你用的是批量式地址类型但收件人列表里填的是自己的个人邮箱而批量投递有专门的频控策略。解决先交DNS记录确认MX、SPF、DKIM全部生效过一小时后重发测试。如果是QQ邮箱收不到控制台“发送记录”里状态是不是“成功”如果是联系收件人加白名单。测试邮件发给阿里云邮箱aliyun.com、alicloud.com后缀最不容易被截胡先用它验证链路通不通。5.3 大附件发不出去邮件推送不是网盘现象附件超过5MB接口返回InvalidAttachment或直接超时。原因邮件推送服务对附件大小有限制单封邮件总大小不建议超过10MB普通附件建议在5MB以内并且不支持断点续传。在云环境里发大附件本身就是对投递服务的一种压力。解决不要把邮件推送当文件传输工具。附件上传到OSS邮件里放一个“点击下载”的链接链接有效期用STS临时凭证控制。这样邮件体积小送达率高还能统计哪些人点了链接。5.4 批量发信总是部分失败收件人列表格式现象BatchSendMail返回成功但控制台批次详情里显示一部分收件人投递失败错误码是InvalidAddress。原因收件人列表里混入了格式不对的地址或者自定义字段里带了特殊字符。最常见的是detail字段里用中文逗号服务端只认英文逗号导致解析错位。解决在调CreateReceiverDetail之前做一次数据清洗规范化邮箱地址小写化、去空格校验邮箱正则^[a-zA-Z0-9_.-][a-zA-Z0-9-]\.[a-zA-Z0-9-.]$字段分隔符统一转成英文逗号对非法数据打标跳过而不是中断整个列表。5.5 clickTrace打开后邮件里多了一段像素代码现象邮件在收件人侧显示异常或者企业安全网关拦截了邮件。原因clickTrace1时SDK会在邮件中注入一个1x1像素的追踪图片和链接重定向代码。部分企业邮箱安全策略会拦截带外链图片的邮件。解决如果业务不依赖打开率和点击率数据直接传0。如果一定要追踪数据建议先小范围内测确认收件方安全策略能放行后再全量启用。5.6 模板审核状态永远是“审核中”现象模板创建后状态一直不变调用发送接口报TemplateUnavailable。原因模板内容包含营销词汇或疑似诱导链接人工审核没通过或排队时间较长。解决模板审核是人工的可做的有限内容避免“点击领取”“立即购买”“特惠”这类营销敏感词链接域名和发信域名保持一致需要加急时走工单系统联系售后说明模板用途和发送场景。审核一般是工作日处理周五下午提交的模板周一上午才有结果提前规划好发信排期。6. 进阶思路把邮件发送从“调通”变成“稳定服务”邮件推送调通之后下一步是把发信能力接进你现有的技术体系。我在生产环境里沉淀了几个做法谈不上多高级但能解决真实问题。信号量限速。SDK内部有重试机制但重试逻辑不会解决限流问题。在业务代码与SDK之间加一个信号量或者令牌桶控制并发发送速率。我习惯的做法是根据控制台配额算出一个保守的每秒并发数例如日配额5万、工作8小时每秒并发不超过2留出余量应对峰值。这个数字写进配置中心方便随时调。异步化分离。把邮件发送从业务请求链路中剥离。用户下单成功后不直接在事务里同步调邮件接口而是把邮件任务塞进MNS消息队列或RocketMQ消费者异步取走任务并调用邮件SDK。好处是邮件发送有抖动时不影响下单链路发送失败可以进入重试队列业务高峰期可以通过增加消费者数量弹性扩容。这个结构下邮件接口超时、限流、报错都影响不到核心业务了。链路追踪。发信的RequestId要记录到日志系统并在日志中关联业务ID比如订单号、用户ID。排查“用户说没收到验证码后台显示发送成功”这类问题时没有RequestId只能靠猜有RequestId可以对接控制台查完整投递链路。监控告警。用QueryMailDetailByParam定时拉取最近一小时的发送详情统计成功率和退信率。成功率低于99%或者退信率超过2%触发告警。退信率异常通常不是阿里云的问题而是你的收件人列表里有大量失效地址需要做列表清洗。这套监控脚本用什么语言写都行核心是要有。灰度发信。模板上线不要直接全量。先把收件人列表切成1%的小批次发出去观察半小时送达率和垃圾箱投诉率再逐步放量到10%、50%、100%。控制台里“发送记录”支持按批次筛选切量之前先在测试列表上验证一遍文案和链接有效性。这个习惯帮我挡掉过好多次错版HTML模板全量炸发的惨剧。保持第一时间回到手册翻“错误码参考”表的习惯。遇到读不懂的报错不要立刻翻代码先查手册里的错误码分类多数问题其实在手册的“公共错误码”和“业务错误码”两张表里写得清清楚楚。把报错和手册对上号再决定是改参数还是提工单效率会高很多。希望帮到你。本文还有配套的精品资源点击获取