Spring Boot 发送邮件

2023-11-03

Spring Boot 对于发送邮件这种常用功能也提供了开箱即用的 Starter：spring-boot-starter-mail。

通过这个 starter，只需要简单的几行配置就可以在 Spring Boot 中实现邮件发送，可用于发送验证码、账户激活等等业务场景。

本文将通过实际的案例带你了解如何在 Spring Boot 中使用 QQ 邮箱发送邮件。

关于 Spring 对邮件支持的更多细节，你可以参阅中文文档。

创建 Spring Boot 应用

在 pom.xml 中添加 spring-boot-starter-mail 依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-mail</artifactId>
</dependency>

属性配置

在 application.yaml 中配置属性。

spring:
  mail:
    # 指定邮件服务器地址
    host: smtp.qq.com
    # 登录账户
    username: 747692844@qq.com
    # 登录密码
    password: "<你的密码/授权码>"
    # 端口
    port: 465
    # 默认编码
    default-encoding: UTF-8
    # 使用的协议
    protocol: smtps
    # 其他的属性
    properties:
      "mail.smtp.connectiontimeout": 5000
      "mail.smtp.timeout": 3000
      "mail.smtp.writetimeout": 5000
      "mail.smtp.auth": true
      "mail.smtp.starttls.enable": true
      "mail.smtp.starttls.required": true

需要在 QQ 邮箱设置中开启 SMTP 服务，并且记得把配置文件中的 spring.mail.password 替换为你的 授权码。注意，不是 QQ 密码，关于 QQ 邮箱如何生成授权码你可以参阅官方文档。

对于 spring mail 更多的可用配置可以参阅 Spring Boot 中文文档。

发送邮件

配置正确后，就可以在任意 Bean 中注入 JavaMailSender Bean，用于发送邮件。

发送一封简单的邮件：

@Autowired
JavaMailSender javaMailSender;

@Test
public void test() throws Exception {

    // 创建一个邮件消息
    MimeMessage message = javaMailSender.createMimeMessage();

    // 创建 MimeMessageHelper
    MimeMessageHelper helper = new MimeMessageHelper(message, false);

    // 发件人邮箱和名称
    helper.setFrom("747692844@qq.com", "springdoc");
    // 收件人邮箱
    helper.setTo("admin@springboot.io");
    // 邮件标题
    helper.setSubject("Hello");
    // 邮件正文，第二个参数表示是否是HTML正文
    helper.setText("Hello <strong> World</strong>！", true);
    
    // 发送
    javaMailSender.send(message);
}

首先，通过 javaMailSender 的 createMimeMessage 创建一个 MimeMessage 对象，表示邮件。

接着创建 MimeMessageHelper 对象，第二个 boolean 参数表示，是否是一个 Multipart 邮件（带有附件）。

然后，通过 helper 对象，设置邮件的发件人邮箱和名称、收件人、主题、内容等信息。注意，setText 方法第二个参数表示内容是否是 html 正文。本例中，正文使用了一个 strong HTML 标签。

执行测试，发送邮件。然后进入收件箱查看：

收到来自于 springdoc.cn 的邮件

成功收件，注意 World 文本是加粗的，因为发送的是 HTML 邮件，并且使用了 strong 标签。

可以使用 freemarker 等模板模板引擎来定义 HTML 邮件模板。

发送带有附件的邮件

有时，我们需要通过邮箱发送一些附件文件。

如下：

@Autowired
JavaMailSender javaMailSender;

@Test
public void test() throws Exception {

    // 创建一个邮件消息
    MimeMessage message = javaMailSender.createMimeMessage();

    // 创建 MimeMessageHelper，指定 boolean multipart 参数为 true
    MimeMessageHelper helper = new MimeMessageHelper(message, true);

    // 发件人邮箱和名称
    helper.setFrom("747692844@qq.com", "springdoc");
    // 收件人邮箱
    helper.setTo("admin@springboot.io");
    // 邮件标题
    helper.setSubject("Spring 中文文档");
    // 邮件正文，第二个参数表示是否是HTML正文
    helper.setText("你好，这是 Spirng 的中文文档！<br/> 请尽快下载！", true);
    
    // 添加一个附件，指定附件名称、文件的 Inputstream 流 以及 Content-Type
    helper.addAttachment("spring-framework 中文文档.pdf", 
            () -> Files.newInputStream(Paths.get("C:\\Users\\KevinBlandy\\Desktop\\spring-framework 中文文档.pdf")), 
            "application/octet-stream");
    
    // 发送
    javaMailSender.send(message);
}

如上，和发送普通邮件没太大区别。

创建 MimeMessageHelper 时，第二个参数要设置为 true。
调用 helper 的 addAttachment() 方法来添加附件，可以多次调用表示添加多个。

addAttachment() 方法的第一个参数就是会在收件箱显示的附件名称，第二个参数是一个 InputStreamSource 函数接口，需要返回一个 InputStream，也就是附件文件的二进制流。最后一个参数用于表示文件的媒体类型，也就是 Content Type，如果你不知道具体的类型，可以无脑设置为 application/octet-stream。

同样，这封邮件也是 HTML 邮件，在正文中使用了 <br/> 标签。

执行测试，发送邮件，并且查看收到的邮件：

收到了带有附件的邮件

如上，成功收到了带附件的邮件。

自定义 JavaMailSender 实现

上面的例子中，我们把邮箱的信息定义在了配置文件中。这可能有一些不够灵活，你也可以把邮箱信息存储在数据库或者其他地方，随时可以通过管理后台进行维护、修改，而不需要重启应用。

我们可以直接实例化 JavaMailSender 的默认实现 JavaMailSenderImpl，在运行时设置邮箱服务器、用户名密码等等。

@Test
public void test() throws Exception {
    
    // 直接创建 JavaMailSenderImpl 实现类
    JavaMailSenderImpl javaMailSender = new JavaMailSenderImpl();
    
    javaMailSender.setDefaultEncoding("utf-8");

    javaMailSender.setHost("smtp.qq.com");              // 设置邮箱服务器
    javaMailSender.setPort(465);                        // 设置端口
    javaMailSender.setUsername("747692844@qq.com");    // 设置用户名
    javaMailSender.setPassword("<你的密码/授权码>");      // 设置密码（记得替换为你实际的密码、授权码）
    javaMailSender.setProtocol("smtps");                // 设置协议
    
    Properties properties = new Properties();           // 配置项
    properties.put("mail.smtp.connectiontimeout", 5000);
    properties.put("mail.smtp.timeout", 3000);
    properties.put("mail.smtp.writetimeout", "5000");
    properties.put("mail.smtp.auth", true);
    properties.put("mail.smtp.starttls.enable", true);
    properties.put("mail.smtp.starttls.required", true);
    
    
    javaMailSender.setJavaMailProperties(properties); // 设置配置项
    
    // 创建一个邮件消息
    MimeMessage message = javaMailSender.createMimeMessage();

    // 创建 MimeMessageHelper
    MimeMessageHelper helper = new MimeMessageHelper(message, false);

    // 发件人邮箱和名称
    helper.setFrom("747692844@qq.com", "springdoc");
    // 收件人邮箱
    helper.setTo("admin@springboot.io");
    // 邮件标题
    helper.setSubject("Hello");
    // 邮件正文，第二个参数表示是否是HTML正文
    helper.setText("Hello <strong> World</strong>！", true);
    
    // 发送
    javaMailSender.send(message);
}

如上，每次发送邮件都先从数据库中检索邮箱服务器的配置，然后构建 JavaMailSenderImpl 实例执行邮件发送。

当需要修改邮箱的时候，只需要在管理后台进行修改即可，不用改动任何配置、代码。