SpringBoot邮件发送之文本邮件与HTML邮件的实现步骤

<!-- SpringBoot 邮件发送核心依赖，自动引入 JavaMail 相关依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-mail</artifactId>
</dependency>
<!-- 可选：lombok，简化代码，无需写getter/setter、log日志等 -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional> <!-- 可选依赖，不影响其他模块 -->
</dependency>
<!-- 可选：spring-boot-starter-web，用于提供测试接口，若项目已引入可忽略 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

spring:
  mail:
    # 发件人邮箱地址（QQ/163/企业邮箱均可，需与下方SMTP地址对应）
    username: 123456@qq.com
    # 授权码（不是邮箱登录密码！是上一步获取的第三方应用授权码）
    password: abcdefghijklmnop
    # SMTP 服务器地址（对应邮箱，不可写错，QQ邮箱：smtp.qq.com；163邮箱：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 加密
          # 邮件发送端口，推荐 587（TLS），465（SSL）也可，需与加密方式对应
          port: 587
        # 超时设置（单位：毫秒），避免网络波动、服务器响应慢导致发送超时
        timeout: 10000 # 邮件发送超时时间
        connectiontimeout: 10000 # 连接服务器超时时间
        writetimeout: 10000 # 写入数据超时时间
# 日志配置（可选，用于排查邮件发送问题，开发环境建议开启）
logging:
  level:
    # 开启 Spring 邮件发送相关日志，DEBUG 级别可查看完整发送流程
    org.springframework.mail: DEBUG
    # 开启自定义邮件相关日志（替换为自己的包名）
    com.example.mail: INFO

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;
        }
    }
}

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 lang='zh-CN'>" +
                "<head><meta charset='UTF-8'><title>" + subject + "</title></head>" +
                "<body style='font-family: \"Microsoft YaHei\", sans-serif;'>" +
                "<div style='width: 600px; margin: 0 auto; padding: 20px; border: 1px solid #eee; border-radius: 5px;'>" +
                "<h2 style='color: #1E90FF; text-align: center; margin-bottom: 20px;'>用户注册验证</h2>" +
                "<p style='font-size: 14px; line-height: 1.5;'>尊敬的用户，您好！</p>" +
                "<p style='font-size: 14px; line-height: 1.5;'>您正在进行注册验证，本次验证码为：</p>" +
                "<div style='font-size: 24px; color: #FF4500; font-weight: bold; text-align: center; margin: 15px 0;'>123456</div>" +
                "<p style='font-size: 14px; line-height: 1.5;'>验证码有效期为 5 分钟，请在有效期内完成验证。</p>" +
                "<p style='font-size: 14px; line-height: 1.5;'>若您未发起注册操作，请忽略此邮件，感谢您的支持！</p>" +
                "<p style='font-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, // 多收件人邮箱地址数组（必填，格式：xxx@qq.com,xxx@163.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 lang='zh-CN'>" +
                "<body style='font-family: \"Microsoft YaHei\", sans-serif;'>" +
                "<h2 style='color: #1E90FF; text-align: center;'>批量通知邮件</h2>" +
                "<p style='font-size: 14px;'>各位用户，您好！本次批量通知内容如下：</p>" +
                "<p style='font-size: 14px; color: #333;'>系统将于今晚 23:00 进行升级维护，维护期间可能无法正常使用，敬请谅解！</p>" +
                "<p style='font-size: 12px; color: #999; margin-top: 20px;'>此为系统批量发送邮件，请勿回复</p>" +
                "</body></html>";
        mailUtil.sendHtmlMail(to, subject, htmlContent);
        return "多收件人HTML邮件发送成功！共发送 " + to.length + " 个收件人";
    }
}