邮件工具 - MailUtil

---

简介

MailUtil 是 Hutool 提供的一个方便邮件发送的工具类，基于 Java 的 javax.mail 包进行了封装，简化了邮件发送的流程。通过 MailUtil，可以轻松实现文本邮件、HTML 邮件、带附件邮件等多种邮件发送需求。由于依赖第三方库，MailUtil 被归类到 extra 模块中。

---

依赖引入

在使用 MailUtil 时，需要先在项目中引入依赖：

<dependency>
    <groupId>com.sun.mail</groupId>
    <artifactId>javax.mail</artifactId>
    <version>${mail.version}</version>
</dependency>

注意：com.sun.mail 是 javax.mail 升级后的版本，确保使用最新的版本以避免兼容性问题。

---

1. 邮件服务器配置

MailUtil 使用一个配置文件 mail.setting 来管理邮件服务器信息。你可以将此文件放置在 src/main/resources/config 目录下。以下是一个最小化配置示例：

# 发件人邮箱地址（必须正确填写）
from = hutool@yeah.net
# 邮箱密码或授权码（视邮箱提供商而定）
pass = q1w2e3

对于需要自定义 SMTP 服务器地址和端口的情况，完整的配置文件示例如下：

# 邮件服务器的SMTP地址
host = smtp.yeah.net
# 邮件服务器的SMTP端口
port = 25
# 发件人邮箱地址
from = hutool@yeah.net
# 发件人用户名（默认取邮箱前缀）
user = hutool
# 邮箱密码或授权码
pass = q1w2e3

参数说明：

• host：SMTP 服务器地址，默认为 smtp.<邮箱域名>，例如 smtp.yeah.net。
• port：SMTP 服务器端口，默认端口为 25。如果使用 SSL 连接，通常为 465。
• from：发件人邮箱地址。
• user：发件人用户名，默认为邮箱前缀部分。
• pass：邮箱密码或授权码，授权码通常用于更安全的 SMTP 认证。

实际开发场景：配置文件用于指定默认的邮件服务器和账号信息，可以方便地复用该配置文件来发送邮件，而无需在代码中重复配置。

---

2. 发送邮件

示例 1：发送普通文本邮件

import cn.hutool.extra.mail.MailUtil;

public class MailExample {
    public static void main(String[] args) {
        // 使用 MailUtil 发送简单文本邮件
        MailUtil.send("recipient@example.com", "测试邮件", "这是一封来自 Hutool 的测试邮件", false);
    }
}

代码解读：

• recipient@example.com：收件人邮箱地址。
• "测试邮件"：邮件主题。
• "这是一封来自 Hutool 的测试邮件"：邮件正文内容。
• false：表示邮件正文不是 HTML 格式。

适用场景：发送系统通知、告警邮件、自动化任务结果等不带格式的简单文本邮件。

---

示例 2：发送带附件的 HTML 邮件

import cn.hutool.extra.mail.MailUtil;
import cn.hutool.core.io.FileUtil;

public class MailExample {
    public static void main(String[] args) {
        // 使用 MailUtil 发送带附件的 HTML 邮件
        MailUtil.send(
            "recipient@example.com", // 收件人
            "测试HTML邮件", // 邮件主题
            "<h1>邮件来自 Hutool</h1>", // HTML 格式的邮件内容
            true, // 表示邮件内容为 HTML
            FileUtil.file("d:/attachment.pdf") // 附件文件
        );
    }
}

代码解读：

• 可以添加多个附件，只需传入多个 File 对象。
• 通过设置 true，表示邮件正文内容为 HTML 格式，可以在邮件中使用 HTML 标签进行内容排版。

适用场景：发送带有格式化内容（如报告、通知）或需要附加文件的邮件。

---

3. 群发邮件

import cn.hutool.extra.mail.MailUtil;
import cn.hutool.core.collection.CollUtil;

public class MailExample {
    public static void main(String[] args) {
        // 使用 MailUtil 群发邮件
        MailUtil.send(
            CollUtil.newArrayList(
                "person1@example.com", 
                "person2@example.com"
            ),
            "测试群发邮件", // 邮件主题
            "这是 Hutool 的群发测试邮件", // 邮件内容
            false // 表示邮件内容为普通文本
        );
    }
}

代码解读：

• 通过 CollUtil.newArrayList 创建收件人列表，支持发送同一内容给多个接收者。
• 此方法适合批量通知、多方会议邀请等场景。

实际开发场景：发送公司内部通知、批量营销邮件等。

---

4. 自定义邮件服务器配置

如果需要在代码中动态配置邮件服务器，可以使用 MailAccount 类：

import cn.hutool.extra.mail.MailUtil;
import cn.hutool.extra.mail.MailAccount;
import cn.hutool.core.collection.CollUtil;

public class MailExample {
    public static void main(String[] args) {
        // 创建自定义邮件服务器配置
        MailAccount account = new MailAccount();
        account.setHost("smtp.yeah.net");
        account.setPort(25);
        account.setAuth(true);
        account.setFrom("hutool@yeah.net");
        account.setUser("hutool");
        account.setPass("q1w2e3");

        // 使用自定义配置发送邮件
        MailUtil.send(account, CollUtil.newArrayList("recipient@example.com"), "测试邮件", "邮件来自 Hutool", false);
    }
}

代码解读：

• MailAccount 可以灵活配置不同的邮件服务器信息。
• 使用场景包括：不同系统或环境需要使用不同的邮件服务器。

---

5. 使用 SSL 发送邮件

某些邮件服务商（如 QQ 邮箱、Gmail）要求使用 SSL 加密连接。配置方法如下：

# mail.setting 文件配置
host = smtp.yeah.net
port = 465
from = hutool@yeah.net
user = hutool
pass = q1w2e3
sslEnable = true

代码解读：

• 设置 sslEnable = true 以启用 SSL 安全连接。
• 完整配置文件中还可以配置 socketFactoryClass 和 socketFactoryPort 等参数，以确保 SSL 连接的稳定性。

实际开发场景：使用 QQ 邮箱、Gmail 等服务时，需要确保启用 SSL 以通过认证。

---

6. 处理邮件发送中的常见问题

示例：处理 PKIX 路径错误（since 5.6.4）

在使用 SSL 发送邮件时，可能会遇到 SSL 验证错误：

import cn.hutool.extra.mail.MailUtil;
import cn.hutool.extra.mail.MailAccount;
import com.sun.mail.util.MailSSLSocketFactory;

public class MailExample {
    public static void main(String[] args) throws Exception {
        // 创建自定义邮件账户配置
        MailAccount mailAccount = new MailAccount();
        mailAccount.setAuth(true);
        mailAccount.setSslEnable(true);

        // 设置跳过 SSL 验证
        MailSSLSocketFactory sf = new MailSSLSocketFactory();
        sf.setTrustAllHosts(true);
        mailAccount.setCustomProperty("mail.smtp.ssl.socketFactory", sf);

        // 发送邮件
        MailUtil.send(mailAccount, CollUtil.newArrayList("recipient@example.com"), "测试邮件", "邮件内容", false);
    }
}

代码解读：

• 通过 MailSSLSocketFactory 设置 setTrustAllHosts(true)，跳过 SSL 证书验证。

适用场景：遇到 SSL 证书路径验证问题时，通过此方法绕过验证以确保邮件发送。

---

这样总结后，涵盖了依赖引入、配置、使用方法、常见问题处理等内容，并且代码块中包含了详细注释，提供了实际开发中的应用场景和完整代码示例。如果还有其他需求，请随时告诉我！