在SpringBoot 项目中邮件发送是不可或缺的基础功能广泛应用于用户注册验证、密码找回、系统告警、订单通知等核心场景。SpringBoot 提供的 spring-boot-starter-mail 组件基于 JavaMail 完成了底层协议封装与自动化配置无需开发者手动处理 SMTP 连接、编码适配等繁琐操作。一、核心基础1. 协议说明发送邮件的核心依赖是SMTP 协议Simple Mail Transfer Protocol简单邮件传输协议负责将邮件从发件人服务器传递到收件人服务器。推荐使用加密端口 587TLS 加密安全性更高可有效避免邮件被拦截或篡改非加密端口 25 因易被垃圾邮件利用多数服务器已屏蔽不推荐使用。2. 核心组件详解Spring 自动注入无需手动实例化•JavaMailSender邮件发送的核心接口封装了邮件发送的所有核心操作连接服务器、发送邮件、关闭连接等SpringBoot 会根据配置文件自动创建实例。•SimpleMailMessage专门用于发送纯文本邮件的工具类用法简洁仅支持文本内容、收件人、主题等基础配置不支持样式、附件。•MimeMessageHelper复杂邮件的辅助工具类简化 HTML 邮件、带附件邮件、多收件人抄送/密送等场景的配置解决中文乱码、样式解析等常见问题。3. 核心应用场景• 纯文本邮件适用于系统告警、简单通知如服务器异常提醒、操作日志通知特点是简洁、发送速度快无需复杂样式。• HTML 富文本邮件适用于用户交互类场景如注册验证码、密码找回、订单通知、活动营销支持文字样式、图片、链接、表格等提升用户体验是实际开发中最常用的邮件类型。二、环境准备关键步骤缺一不可发送邮件前必须开启发件人邮箱的 SMTP 服务并获取「授权码」—— 授权码是第三方应用如 SpringBoot 项目访问邮箱的专用密钥不同于邮箱登录密码目的是保障邮箱账号安全防止密码泄露。不同邮箱的开启方式略有差异以下是最常用的两种邮箱操作步骤详细且可直接对照操作。1. QQ邮箱1. 登录 QQ 邮箱网页版https://mail.qq.com/点击顶部导航栏的「设置」选择左侧「账户」选项2. 下拉页面找到「POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务」模块点击「开启POP3/SMTP服务」3. 根据提示用绑定 QQ 邮箱的手机发送短信验证验证通过后系统会自动生成一串授权码复制并保存建议存放在配置文件中丢失可重新生成4. 记住 QQ 邮箱的 SMTP 服务器地址smtp.qq.com推荐使用端口587TLS 加密若 587 端口不可用可切换为 465SSL 加密。2. 163邮箱1. 登录 163 邮箱网页版https://mail.163.com/点击顶部「设置」选择「POP3/SMTP/IMAP」选项2. 在「SMTP 服务」模块点击「开启」若未设置过授权码需先设置授权码建议设置复杂密码与邮箱登录密码区分开设置完成后保存3. 163 邮箱的 SMTP 服务器地址smtp.163.com推荐端口587TLS 加密465SSL 加密同样支持可根据服务器环境选择。三、SpringBoot 集成配置SpringBoot 对邮件发送进行了自动化配置仅需引入核心依赖、配置相关参数即可快速集成无需编写额外的配置类特殊场景除外。1. 核心依赖pom.xml仅需引入邮件核心 starterlombok 用于简化代码可选但推荐可避免编写 getter/setter、日志输出等冗余代码无需引入其他额外依赖。!-- SpringBoot 邮件发送核心依赖自动引入 JavaMail 相关依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-mail/artifactId /dependency !-- 可选lombok简化代码无需写getter/setter、log日志等 -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional !-- 可选依赖不影响其他模块 -- /dependency !-- 可选spring-boot-starter-web用于提供测试接口若项目已引入可忽略 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency2. 单邮箱配置application.yml配置发件人邮箱、授权码、SMTP 服务器地址、编码格式、超时时间等核心参数注释清晰可直接替换为自己的邮箱信息避免因配置错误导致发送失败。spring: mail: # 发件人邮箱地址QQ/163/企业邮箱均可需与下方SMTP地址对应 username: 123456qq.com # 授权码不是邮箱登录密码是上一步获取的第三方应用授权码 password: abcdefghijklmnop # SMTP 服务器地址对应邮箱不可写错QQ邮箱smtp.qq.com163邮箱smtp.163.com host: smtp.qq.com # 编码格式固定为 UTF-8避免邮件标题、内容出现中文乱码 default-encoding: UTF-8 # 额外配置解决超时、加密、认证等问题生产环境必配 properties: mail: smtp: # 必须开启 SMTP 认证true否则邮箱服务器会拒绝发送请求 auth: true # 开启 TLS 加密提升邮件发送安全性避免邮件被拦截 starttls: enable: true required: true # 强制使用 TLS 加密 # 邮件发送端口推荐 587TLS465SSL也可需与加密方式对应 port: 587 # 超时设置单位毫秒避免网络波动、服务器响应慢导致发送超时 timeout: 10000 # 邮件发送超时时间 connectiontimeout: 10000 # 连接服务器超时时间 writetimeout: 10000 # 写入数据超时时间 # 日志配置可选用于排查邮件发送问题开发环境建议开启 logging: level: # 开启 Spring 邮件发送相关日志DEBUG 级别可查看完整发送流程 org.springframework.mail: DEBUG # 开启自定义邮件相关日志替换为自己的包名 com.example.mail: INFO四、核心代码采用「工具类封装 接口测试」的模式将邮件发送逻辑封装为通用工具类便于在项目中复用提供测试接口可快速验证邮件发送功能同时补充异常处理、日志输出确保代码的健壮性。1. 封装邮件工具类 MailUtil整合纯文本邮件、HTML 富文本邮件的发送方法支持单收件人、多收件人添加异常捕获和日志记录避免发送失败影响主流程同时补充代码注释便于后续维护和修改。import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Value; import org.springframework.mail.SimpleMailMessage; import org.springframework.mail.javamail.JavaMailSender; import org.springframework.mail.javamail.MimeMessageHelper; import org.springframework.stereotype.Component; import javax.mail.MessagingException; import javax.mail.internet.MimeMessage; /** * 邮件发送工具类聚焦文本、HTML 两种常用邮件适配多场景复用 * 注工具类使用 Component 注解交给 Spring 管理可在 Service、Controller 中直接注入使用 */ Slf4j // lombok 注解自动生成 log 日志对象无需手动创建 Component RequiredArgsConstructor // lombok 注解自动注入构造方法无需写 Autowired public class MailUtil { // 核心发送接口SpringBoot 自动根据配置文件创建实例直接注入即可 private final JavaMailSender javaMailSender; // 从 application.yml 配置文件中读取发件人邮箱无需硬编码 Value(${spring.mail.username}) private String defaultFromMail; // 1. 发送纯文本邮件重载方法支持单收件人、多收件人适配不同场景 /** * 单收件人文本邮件 * param to 收件人邮箱地址单个 * param subject 邮件主题 * param content 邮件纯文本内容 */ public void sendTextMail(String to, String subject, String content) { sendTextMail(new String[]{to}, subject, content); } /** * 多收件人文本邮件 * param to 收件人邮箱地址数组多个 * param subject 邮件主题 * param content 邮件纯文本内容 */ public void sendTextMail(String[] to, String subject, String content) { try { // 创建纯文本邮件实例 SimpleMailMessage message new SimpleMailMessage(); message.setFrom(defaultFromMail); // 设置发件人从配置文件读取避免硬编码 message.setTo(to); // 设置收件人可单个、可多个 message.setSubject(subject); // 设置邮件主题 message.setText(content); // 设置邮件纯文本内容 javaMailSender.send(message); // 发送邮件 log.info(纯文本邮件发送成功收件人{}邮件主题{}, String.join(,, to), subject); } catch (Exception e) { // 捕获所有异常记录日志避免影响主流程 log.error(纯文本邮件发送失败收件人{}邮件主题{}异常信息{}, String.join(,, to), subject, e.getMessage(), e); // 抛出运行时异常由调用方根据业务需求处理如重试、返回错误信息 throw new RuntimeException(文本邮件发送失败请稍后重试, e); } } // 2. 发送 HTML 富文本邮件重载方法支持单收件人、多收件人带样式 /** * 单收件人 HTML 邮件 * param to 收件人邮箱地址单个 * param subject 邮件主题 * param htmlContent HTML 格式的邮件内容支持样式、链接、图片等 * throws MessagingException 邮件发送相关异常如配置错误、网络问题 */ public void sendHtmlMail(String to, String subject, String htmlContent) throws MessagingException { sendHtmlMail(new String[]{to}, subject, htmlContent); } /** * 多收件人 HTML 邮件 * param to 收件人邮箱地址数组多个 * param subject 邮件主题 * param htmlContent HTML 格式的邮件内容支持样式、链接、图片等 * throws MessagingException 邮件发送相关异常如配置错误、网络问题 */ public void sendHtmlMail(String[] to, String subject, String htmlContent) throws MessagingException { try { // 创建复杂邮件实例支持 HTML、附件、内嵌图片等 MimeMessage message javaMailSender.createMimeMessage(); // 创建辅助类第一个参数邮件实例第二个参数true 表示支持多部分内容如 HTML第三个参数编码格式 MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(defaultFromMail); // 发件人 helper.setTo(to); // 收件人多收件人传入数组 helper.setSubject(subject); // 邮件主题 // 第二个参数 true开启 HTML 解析否则会将 HTML 标签显示为纯文本 helper.setText(htmlContent, true); javaMailSender.send(message); // 发送邮件 log.info(HTML 邮件发送成功收件人{}邮件主题{}, String.join(,, to), subject); } catch (MessagingException e) { log.error(HTML 邮件发送失败收件人{}邮件主题{}异常信息{}, String.join(,, to), subject, e.getMessage(), e); // 抛出异常由调用方处理如返回错误信息、重试 throw e; } } }2. 测试接口 Controller提供 REST 接口可通过 Postman、浏览器直接调用测试覆盖单收件人、多收件人、文本邮件、HTML 邮件等核心场景接口参数清晰注释详细实际项目中可直接复用或根据业务需求修改。import lombok.RequiredArgsConstructor; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import javax.mail.MessagingException; /** * 邮件发送测试接口实际项目中可整合到 Service 层结合业务场景调用 * 接口采用 GET 请求方便快速测试正式环境可根据需求改为 POST 请求 */ RestController RequestMapping(/mail) // 接口统一前缀便于管理 RequiredArgsConstructor public class MailController { // 注入邮件工具类直接调用发送方法 private final MailUtil mailUtil; // 测试发送纯文本邮件单收件人GET请求方便快速测试 GetMapping(/send/text) public String sendTextMail( RequestParam String to, // 收件人邮箱地址必填 RequestParam String subject, // 邮件主题必填 RequestParam String content // 邮件纯文本内容必填 ) { mailUtil.sendTextMail(to, subject, content); return 纯文本邮件发送成功; } // 测试发送 HTML 富文本邮件单收件人GET请求方便快速测试 GetMapping(/send/html) public String sendHtmlMail( RequestParam String to, // 收件人邮箱地址必填 RequestParam String subject // 邮件主题必填 ) throws MessagingException { // 构建 HTML 内容支持样式、链接、表格等可根据实际业务需求修改 // 示例模拟用户注册验证邮件包含验证码、链接等核心元素 String htmlContent !DOCTYPE html html langzh-CN headmeta charsetUTF-8title subject /title/head body stylefont-family: \Microsoft YaHei\, sans-serif; div stylewidth: 600px; margin: 0 auto; padding: 20px; border: 1px solid #eee; border-radius: 5px; h2 stylecolor: #1E90FF; text-align: center; margin-bottom: 20px;用户注册验证/h2 p stylefont-size: 14px; line-height: 1.5;尊敬的用户您好/p p stylefont-size: 14px; line-height: 1.5;您正在进行注册验证本次验证码为/p div stylefont-size: 24px; color: #FF4500; font-weight: bold; text-align: center; margin: 15px 0;123456/div p stylefont-size: 14px; line-height: 1.5;验证码有效期为 5 分钟请在有效期内完成验证。/p p stylefont-size: 14px; line-height: 1.5;若您未发起注册操作请忽略此邮件感谢您的支持/p p stylefont-size: 12px; color: #999; margin-transform: translateY( 30px; text-align: center;此为系统自动发送邮件请勿回复/p /div /body/html; mailUtil.sendHtmlMail(to, subject, htmlContent); return HTML 邮件发送成功; } // 测试多收件人发送纯文本邮件实际场景常用如批量通知 GetMapping(/send/text/batch) public String sendBatchTextMail( RequestParam String[] to, // 多收件人邮箱地址数组必填格式xxxqq.com,xxx163.com RequestParam String subject, // 邮件主题必填 RequestParam String content // 邮件纯文本内容必填 ) { mailUtil.sendTextMail(to, subject, content); return 多收件人文本邮件发送成功共发送 to.length 个收件人; } // 测试多收件人发送 HTML 邮件实际场景常用如批量营销、通知 GetMapping(/send/html/batch) public String sendBatchHtmlMail( RequestParam String[] to, RequestParam String subject ) throws MessagingException { // 复用注册验证 HTML 模板可根据实际需求修改 String htmlContent !DOCTYPE html html langzh-CN body stylefont-family: \Microsoft YaHei\, sans-serif; h2 stylecolor: #1E90FF; text-align: center;批量通知邮件/h2 p stylefont-size: 14px;各位用户您好本次批量通知内容如下/p p stylefont-size: 14px; color: #333;系统将于今晚 23:00 进行升级维护维护期间可能无法正常使用敬请谅解/p p stylefont-size: 12px; color: #999; margin-top: 20px;此为系统批量发送邮件请勿回复/p /body/html; mailUtil.sendHtmlMail(to, subject, htmlContent); return 多收件人HTML邮件发送成功共发送 to.length 个收件人; } }五、关键注意事项• 授权码是核心必须填写正确不可用邮箱登录密码替代否则邮箱服务器会拒绝发送请求导致发送失败若授权码丢失可重新在邮箱设置中生成。• HTML 邮件必须开启helper.setText(htmlContent, true)第二个参数为 true 才会解析 HTML 样式若设为 false会将 HTML 标签显示为纯文本失去样式效果。• 测试时优先使用个人邮箱QQ/163正式环境建议切换为企业邮箱因为个人邮箱有发送频率限制如 QQ 邮箱单日发送上限约 50 封企业邮箱无明显限制稳定性更高。• 若邮件发送失败可开启日志 DEBUG 级别重点排查以下问题授权码错误、SMTP 服务器地址错误、端口错误、网络波动、邮箱 SMTP 服务未开启。• 多收件人发送时直接传入字符串数组String[] to即可无需多次调用发送方法工具类已做好适配避免重复创建连接提升发送效率。• 中文乱码问题确保配置文件中default-encoding: UTF-8同时 MimeMessageHelper 构造方法中指定编码为 UTF-8即可避免中文乱码。• 异常处理工具类中已捕获异常并记录日志实际项目中可根据业务需求添加重试逻辑如失败后重试 2-3 次提升邮件发送成功率。