Java常用邮件发送类库与JavaMail API_技术教程

JavaMail API 是 Oracle 提供的邮件协议抽象层，现已被 Jakarta Mail 取代；推荐使用 Spring 的 JavaMailSender 或 Simple Java Mail 等封装方案以避免底层配置错误。

JavaMail API 是什么，现在还该用吗

JavaMail API 是 Oracle 提供的官方邮件协议抽象层（javax.mail），底层封装了 SMTP/POP3/IMAP 协议交互逻辑。但它本身不实现网络通信，必须搭配具体 Provider（如 smtp.jar）才能工作。从 Java EE 7 开始，它已从 JDK 中移除；Java 11+ 完全不包含，需手动引入依赖。

如果你在用 Spring Boot，spring-boot-starter-mail 底层默认仍基于 JavaMail API（使用 jakarta.mail 迁移版），但屏蔽了大部分底层细节。纯 Java SE 项目若还要手写 Session、MimeMessage、Transport.send()，容易出编码、认证、SSL/TLS 配置错误——这不是 API 设计问题，而是协议细节太琐碎。

Java 8–10：可用 javax.mail:javax.mail-api + com.sun.mail:javax.mail
Java 11+：必须用 Jakarta EE 版本：jakarta.mail:jakarta.mail-api 和 org.eclipse.angus:angus-mail（原 GlassFish Mail 的继任者）
Spring Boot 3.x 已全面切换到 jakarta.mail，直接依赖 spring-boot-starter-mail 即可，无需再管类名迁移

为什么推荐 Spring Framework 的 `JavaMailSender` 而非裸用 JavaMail API

裸调 JavaMail API 写一封带附件的 HTML 邮件，要处理 MIME 类型、字符集、Base64 编码、边界分隔符、Content-ID 引用……稍有不慎就出现乱码、附件打不开、图片不显示。而 JavaMailSender 把这些封装成声明式操作，错误集中在配置阶段（比如 mail.smtp.auth=true 忘设），而非运行时难调试的字节流问题。

关键差异点：

JavaMailSender 是接口，Spring 默认实现是 JavaMailSenderImpl，它自动适配 jakarta.mail.Session，且支持连接池（通过 setSession() 复用）
发送方法统一为 send(MimeMessagePreparator) 或 send(SimpleMailMessage)，避免手动 new MimeMessage 和 setFrom/setRecipients 等易错链式调用
异常类型更明确：MailAuthenticationException、MailSendException 直接对应问题根源，不像裸 API 只抛 javax.mail.AuthenticationFailedException 或底层 IOException

SimpleMailMessage message = new SimpleMailMessage();
message.setFrom("no-reply@example.com");
message.setTo("user@test.com");
message.setSubject("订单确认");
message.setText("您的订单已提交，预计24小时内发货。");
javaMailSender.send(message);

常见失败场景与对应配置项

90% 的邮件发送失败不是代码问题，而是 SMTP 配置与服务商策略不匹配。以下是真实高频报错及解法：

javax.mail.AuthenticationFailedException：检查 mail.smtp.auth 是否为 true，且用户名密码是否为应用专用密码（如 Gmail 开启两步验证后需用 App Password，而非账户登录密码）
Could not convert socket to TLS：说明服务器要求 STARTTLS，但代码用了 mail.smtp.ssl.enable=true（这是 SSL/TLS 直连，端口通常是 465）。应改用 mail.smtp.starttls.enable=true + 端口 587
中文主题/正文乱码：确保 mail.mime.charset=UTF-8，且 SimpleMailMessage 不支持 HTML，要用 MimeMessagePreparator 并显式设置 message.setContent(..., "text/html;charset=UTF-8")
被 Gmail/Outlook 当垃圾邮件：发件人地址必须真实存在且经过 SPF/DKIM/DMARC 验证；避免纯 HTML、过多链接、敏感词；测试时先用公司域名邮箱，别用免费邮箱直连

轻量替代方案：`Simple Java Mail`

如果项目不用 Spring，又嫌 Jakarta Mail 配置太重，Simple Java Mail 是个务实选择。它本质是 JavaMail API 的 fluent 封装，不引入新协议栈，但把所有配置、MIME 构建、异常映射都收拢到一个入口。

优势在于零配置启动（内置主流邮箱默认值）、一行代码发 HTML+附件、支持异步发送、自带日志开关。它内部仍用 jakarta.mail，所以 Java 17+ 兼容性无压力。

Mailer mailer = MailerBuilder
    .withSMTPServer("smtp.gmail.com", 587, "you@gmail.com", "app-password")
    .buildMailer();

Email email = EmailBuilder.startingBlank()
    .from("Me", "me@example.com")
    .to("You", "you@example.com")
    .withSubject("Test")
    .withPlainText("Hi there!")
    .withHTMLText("Hi there!")
    .buildEmail();

mailer.sendMail(email);

注意：它的 Mailer 实例是线程安全的，可单例复用；但不要在高并发下频繁 new Email 对象而不复用 EmailBuilder，否则 GC 压力会上升。