Spring Boot + QQ 邮箱实现邮件推送

2026-03-14 / 2026-03-15 / SpringBoot QQ邮箱邮件推送 SMTP

导语

在现代应用中，邮件推送是一种常见的功能，用于用户注册验证、密码重置、业务通知等场景。QQ邮箱作为国内常用的邮箱服务，提供了稳定的SMTP服务，方便开发者集成到应用中。本文将介绍如何在Spring Boot应用中集成QQ邮箱的SMTP服务，实现邮件推送功能。通过本文的技术方案，您将能够快速实现邮件发送功能，为应用添加通知能力。

一、QQ邮箱SMTP服务配置

1.1 开启SMTP服务

登录QQ邮箱
- 访问 https://mail.qq.com/ 并登录您的QQ邮箱
进入设置页面
- 点击顶部导航栏的「设置」按钮
- 选择「账户」选项卡
开启SMTP服务
- 找到「POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务」部分
- 开启「SMTP服务」
生成授权码
- 点击「生成授权码」
- 按照提示完成验证（通常需要短信验证）
- 复制生成的授权码，这将作为邮件发送的密码

1.2 重要注意事项

授权码而非QQ密码：使用SMTP服务时，需要使用生成的授权码作为密码，而不是QQ登录密码
安全保存：授权码具有与密码相同的权限，需要安全保存
定期更新：如果担心授权码泄露，可以定期重新生成

二、Spring Boot集成邮件发送

2.1 依赖配置

在pom.xml中添加邮件发送依赖：

<dependencies>
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- Spring Boot Mail -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-mail</artifactId>
    </dependency>
    
    <!-- Lombok -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

2.2 邮箱配置

在application.yml中配置邮件发送相关信息：

# 应用配置
spring:
  application:
    name: springboot-qq-email
  
  # 邮件配置
  mail:
    host: smtp.qq.com
    port: 587
    username: your-qq-email@qq.com
    password: your-authorization-code
    default-encoding: UTF-8
    properties:
      mail:
        smtp:
          auth: true
          starttls:
            enable: true
            required: true

# 服务器配置
server:
  port: 8080
  servlet:
    context-path: /

# 日志配置
logging:
  level:
    com.example.email: info
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"

2.3 邮件发送服务

创建邮件发送服务：

@Service
@Slf4j
public class EmailService {
    
    @Autowired
    private JavaMailSender mailSender;
    
    @Value("${spring.mail.username}")
    private String fromEmail;
    
    /**
     * 发送简单邮件
     * @param to 收件人邮箱
     * @param subject 邮件主题
     * @param content 邮件内容
     */
    public void sendSimpleEmail(String to, String subject, String content) {
        SimpleMailMessage message = new SimpleMailMessage();
        message.setFrom(fromEmail);
        message.setTo(to);
        message.setSubject(subject);
        message.setText(content);
        
        try {
            mailSender.send(message);
            log.info("Simple email sent to: {}", to);
        } catch (Exception e) {
            log.error("Failed to send simple email to: {}", to, e);
            throw new RuntimeException("Failed to send email", e);
        }
    }
    
    /**
     * 发送HTML邮件
     * @param to 收件人邮箱
     * @param subject 邮件主题
     * @param htmlContent HTML内容
     */
    public void sendHtmlEmail(String to, String subject, String htmlContent) {
        MimeMessage message = mailSender.createMimeMessage();
        
        try {
            MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
            helper.setFrom(fromEmail);
            helper.setTo(to);
            helper.setSubject(subject);
            helper.setText(htmlContent, true); // true表示发送HTML内容
            
            mailSender.send(message);
            log.info("HTML email sent to: {}", to);
        } catch (Exception e) {
            log.error("Failed to send HTML email to: {}", to, e);
            throw new RuntimeException("Failed to send HTML email", e);
        }
    }
    
    /**
     * 发送带附件的邮件
     * @param to 收件人邮箱
     * @param subject 邮件主题
     * @param content 邮件内容
     * @param attachments 附件列表
     */
    public void sendEmailWithAttachments(String to, String subject, String content, List<EmailAttachment> attachments) {
        MimeMessage message = mailSender.createMimeMessage();
        
        try {
            MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
            helper.setFrom(fromEmail);
            helper.setTo(to);
            helper.setSubject(subject);
            helper.setText(content, true);
            
            // 添加附件
            if (attachments != null && !attachments.isEmpty()) {
                for (EmailAttachment attachment : attachments) {
                    helper.addAttachment(attachment.getFilename(), attachment.getDataSource());
                }
            }
            
            mailSender.send(message);
            log.info("Email with attachments sent to: {}", to);
        } catch (Exception e) {
            log.error("Failed to send email with attachments to: {}", to, e);
            throw new RuntimeException("Failed to send email with attachments", e);
        }
    }
    
    /**
     * 发送模板邮件
     * @param to 收件人邮箱
     * @param subject 邮件主题
     * @param templateName 模板名称
     * @param templateModel 模板模型
     */
    public void sendTemplateEmail(String to, String subject, String templateName, Map<String, Object> templateModel) {
        // 这里可以集成Thymeleaf等模板引擎实现模板邮件
        // 示例代码略
    }
    
    /**
     * 邮件附件类
     */
    @Data
    @AllArgsConstructor
    public static class EmailAttachment {
        private String filename;
        private DataSource dataSource;
    }
}

2.4 控制器实现

创建邮件发送控制器：

@RestController
@RequestMapping("/api/email")
public class EmailController {
    
    @Autowired
    private EmailService emailService;
    
    /**
     * 发送简单邮件
     */
    @PostMapping("/send-simple")
    public ResponseEntity<String> sendSimpleEmail(@RequestBody EmailRequest request) {
        try {
            emailService.sendSimpleEmail(request.getTo(), request.getSubject(), request.getContent());
            return ResponseEntity.ok("Email sent successfully");
        } catch (Exception e) {
            return ResponseEntity.badRequest().body("Failed to send email: " + e.getMessage());
        }
    }
    
    /**
     * 发送HTML邮件
     */
    @PostMapping("/send-html")
    public ResponseEntity<String> sendHtmlEmail(@RequestBody EmailRequest request) {
        try {
            emailService.sendHtmlEmail(request.getTo(), request.getSubject(), request.getContent());
            return ResponseEntity.ok("HTML email sent successfully");
        } catch (Exception e) {
            return ResponseEntity.badRequest().body("Failed to send HTML email: " + e.getMessage());
        }
    }
    
    /**
     * 发送带附件的邮件
     */
    @PostMapping("/send-with-attachments")
    public ResponseEntity<String> sendEmailWithAttachments(@RequestBody EmailRequest request) {
        try {
            // 这里可以根据实际需求处理附件
            // 示例代码略
            emailService.sendEmailWithAttachments(request.getTo(), request.getSubject(), request.getContent(), null);
            return ResponseEntity.ok("Email with attachments sent successfully");
        } catch (Exception e) {
            return ResponseEntity.badRequest().body("Failed to send email with attachments: " + e.getMessage());
        }
    }
    
    // 请求DTO
    @Data
    static class EmailRequest {
        private String to;
        private String subject;
        private String content;
    }
}

2.5 主应用类

@SpringBootApplication
public class EmailApplication {
    public static void main(String[] args) {
        SpringApplication.run(EmailApplication.class, args);
    }
}

三、完整项目结构

springboot-qq-email/
├── src/main/java/com/example/email/
│   ├── EmailApplication.java
│   ├── service/EmailService.java
│   └── controller/EmailController.java
├── src/main/resources/
│   └── application.yml
├── pom.xml
└── README.md

四、生产级实现

4.1 配置优化

application.yml

# 应用配置
spring:
  application:
    name: springboot-qq-email
  
  # 邮件配置
  mail:
    host: smtp.qq.com
    port: 587
    username: ${EMAIL_USERNAME}
    password: ${EMAIL_PASSWORD}
    default-encoding: UTF-8
    properties:
      mail:
        smtp:
          auth: true
          starttls:
            enable: true
            required: true
          connectiontimeout: 5000
          timeout: 5000
          writetimeout: 5000

# 服务器配置
server:
  port: 8080
  servlet:
    context-path: /

# 邮件配置
email:
  # 发送频率限制
  rate-limit:
    enabled: true
    max-per-minute: 60
  # 重试机制
  retry:
    enabled: true
    max-attempts: 3
    backoff-millis: 1000

# 日志配置
logging:
  level:
    com.example.email: info
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"

4.2 性能优化

1. 连接池配置

@Configuration
public class MailConfig {
    
    @Value("${spring.mail.host}")
    private String host;
    
    @Value("${spring.mail.port}")
    private int port;
    
    @Value("${spring.mail.username}")
    private String username;
    
    @Value("${spring.mail.password}")
    private String password;
    
    @Bean
    public JavaMailSender javaMailSender() {
        JavaMailSenderImpl mailSender = new JavaMailSenderImpl();
        mailSender.setHost(host);
        mailSender.setPort(port);
        mailSender.setUsername(username);
        mailSender.setPassword(password);
        
        // 配置连接池
        Properties props = mailSender.getJavaMailProperties();
        props.put("mail.smtp.auth", "true");
        props.put("mail.smtp.starttls.enable", "true");
        props.put("mail.smtp.starttls.required", "true");
        props.put("mail.smtp.connectiontimeout", "5000");
        props.put("mail.smtp.timeout", "5000");
        props.put("mail.smtp.writetimeout", "5000");
        
        return mailSender;
    }
}

2. 异步发送

@Service
@Slf4j
public class AsyncEmailService {
    
    @Autowired
    private EmailService emailService;
    
    @Async
    public CompletableFuture<Boolean> sendEmailAsync(String to, String subject, String content) {
        try {
            emailService.sendSimpleEmail(to, subject, content);
            return CompletableFuture.completedFuture(true);
        } catch (Exception e) {
            log.error("Failed to send email asynchronously", e);
            return CompletableFuture.completedFuture(false);
        }
    }
}

4.3 安全配置

1. 授权码管理

使用环境变量或密钥管理服务存储授权码
避免在代码或配置文件中硬编码

2. 邮件内容安全

验证邮件内容，防止注入攻击
对敏感信息进行脱敏处理
限制邮件大小和附件类型

3. 速率限制

实现邮件发送速率限制
防止滥用导致邮箱被封

五、最佳实践

5.1 邮件内容设计

1. 主题设计

简洁明了，准确反映邮件内容
避免使用敏感词汇，防止被标记为垃圾邮件
可以包含应用名称，便于用户识别

2. 内容设计

保持内容简洁，重点突出
使用HTML格式，提升视觉效果
包含退订链接，符合邮件营销规范

3. 个性化

包含用户姓名等个性化信息
根据用户行为定制邮件内容
提供个性化的操作按钮

5.2 发送策略

1. 批量发送

对大量邮件进行分批处理
使用异步发送，避免阻塞主线程
实现重试机制，处理发送失败的情况

2. 发送时间

选择合适的发送时间，提高邮件打开率
避免在深夜或凌晨发送
考虑不同时区的用户

3. 监控与统计

记录邮件发送状态
统计邮件打开率和点击率
根据统计数据优化邮件内容

5.3 错误处理

1. 异常处理

捕获并记录邮件发送异常
实现重试机制，处理临时失败
对永久失败的邮件进行单独处理

2. 退信处理

监控退信情况
定期清理无效邮箱
分析退信原因，优化发送策略

3. 投诉处理

监控用户投诉情况
及时处理用户投诉
调整邮件发送策略，减少投诉率

六、常见问题及解决方案

6.1 授权码问题

问题：授权码错误导致邮件发送失败

解决方案：

确保使用的是QQ邮箱生成的授权码，而不是QQ密码
重新生成授权码，确保授权码正确
检查授权码是否过期或被撤销

6.2 网络问题

问题：网络连接超时或失败

解决方案：

检查网络连接是否正常
增加连接超时时间
实现重试机制，处理临时网络故障

6.3 被标记为垃圾邮件

问题：邮件被收件人邮箱标记为垃圾邮件

解决方案：

优化邮件内容，避免使用垃圾邮件关键词
确保邮件发送频率合理
提供清晰的退订选项
建立良好的发信声誉

6.4 发送频率限制

问题：QQ邮箱对发送频率有限制

解决方案：

控制发送频率，避免短时间内发送大量邮件
实现速率限制，遵守邮箱服务提供商的规定
考虑使用专业的邮件服务提供商

小结

本文介绍了Spring Boot应用中集成QQ邮箱SMTP服务实现邮件推送的完整解决方案，包括：

QQ邮箱SMTP配置：开启服务并生成授权码
Spring Boot集成：添加依赖并配置邮件参数
邮件发送实现：支持多种类型的邮件发送
生产级优化：连接池配置、异步发送、安全措施
最佳实践：邮件内容设计、发送策略、错误处理
常见问题：解决方案和规避措施

通过实施这些技术方案，您可以构建一个可靠、高效的邮件推送系统，为应用添加通知能力，提升用户体验。

互动话题

您在使用QQ邮箱SMTP服务时遇到过哪些问题？是如何解决的？
您对本文介绍的邮件发送实现有什么改进建议？
您认为在现代应用中，邮件推送还有哪些创新用法？
您对未来邮件发送技术的发展有什么看法？

欢迎在评论区分享您的经验和看法！

标题：Spring Boot + QQ 邮箱实现邮件推送
作者：jiangyi
地址：http://jiangyi.space/articles/2026/03/14/1773209075786.html
公众号：服务端技术精选

导语
一、QQ邮箱SMTP服务配置
1.1 开启SMTP服务
1.2 重要注意事项
二、Spring Boot集成邮件发送
2.1 依赖配置
2.2 邮箱配置
2.3 邮件发送服务
2.4 控制器实现
2.5 主应用类
三、完整项目结构
四、生产级实现
4.1 配置优化
4.2 性能优化
4.3 安全配置
五、最佳实践
5.1 邮件内容设计
5.2 发送策略
5.3 错误处理
六、常见问题及解决方案
6.1 授权码问题
6.2 网络问题
6.3 被标记为垃圾邮件
6.4 发送频率限制
小结
互动话题

0 评论