JavaMail API 完整指南：從核心架構到郵件發送實戰

JavaMail API 核心架構解析

JavaMail API 是 Java 平台上處理電子郵件的標準擴展套件，提供了平台無關、協議無關的郵件收發框架。其核心設計遵循「關注點分離」原則，將郵件處理劃分為三大功能模組：

1. 郵件訊息模型

javax.mail.Message 及其子類 MimeMessage 是郵件內容的核心抽象。每個實例代表一封完整的電子郵件，封裝了發件人、收件人、主題、正文及附件等元素。MimeMessage 支援 MIME 標準，可處理多部分內容、編碼轉換及國際化字符集。

2. 郵件傳輸協議

javax.mail.Transport 負責郵件發送，實現了 SMTP、SMTPAUTH 等協議。透過 Transport.send() 靜態方法或實例化 Transport 對象後調用 connect()、sendMessage()，即可完成郵件投遞。

3. 郵件存取協議

javax.mail.Store 提供郵件接收功能，支援 POP3、IMAP 等協議。開發者可透過 Store 連接郵箱伺服器，獲取 Folder 對象進而讀取、搜尋、刪除郵件。

Session：郵件環境的統一入口

Session 類集中管理郵件會話的環境配置，包括：

• 郵件伺服器主機名、端口
• 傳輸協議、認證機制
• SSL/TLS 安全設置
• 除錯模式開關

Session 採用工廠模式創建 Transport、Store 和 Message 對象，確保配置一致性。可透過 Session.getInstance(props) 或 Session.getDefaultInstance(props) 獲取實例。

實戰：三種常見郵件發送場景

場景一：純文本/HTML 郵件

public class SimpleMailSender {
    public static void main(String[] args) throws Exception {
        Properties props = new Properties();
        props.put("mail.host", "smtp.example.com");
        props.put("mail.transport.protocol", "smtp");
        props.put("mail.smtp.auth", "true");
        props.put("mail.smtp.port", "587");
        props.put("mail.smtp.starttls.enable", "true");

        Session session = Session.getInstance(props);
        session.setDebug(true);

        MimeMessage message = new MimeMessage(session);
        message.setFrom(new InternetAddress("sender@example.com"));
        message.setRecipient(Message.RecipientType.TO, new InternetAddress("recipient@example.com"));
        message.setSubject("測試郵件", "UTF-8");

        MimeBodyPart htmlPart = new MimeBodyPart();
        htmlPart.setContent("<h1>你好，JavaMail!</h1>", "text/html;charset=UTF-8");

        MimeMultipart multipart = new MimeMultipart();
        multipart.addBodyPart(htmlPart);
        message.setContent(multipart);
        message.saveChanges();

        try (Transport transport = session.getTransport()) {
            transport.connect("username", "password");
            transport.sendMessage(message, message.getAllRecipients());
        }
    }
}

場景二：嵌入圖片的富文本郵件

關鍵在於使用 cid: 協議引用內嵌資源，並將 MimeMultipart 子類型設為 related：

MimeBodyPart htmlPart = new MimeBodyPart();
htmlPart.setContent("<img src='cid:logo.png'>", "text/html;charset=UTF-8");

MimeBodyPart imagePart = new MimeBodyPart();
imagePart.attachFile(new File("logo.png"));
imagePart.setContentID("<logo.png>");

MimeMultipart related = new MimeMultipart("related");
related.addBodyPart(htmlPart);
related.addBodyPart(imagePart);
message.setContent(related);

場景三：帶附件的混合郵件

採用巢狀 MimeMultipart 結構：外層 mixed 包含內層 related（正文+圖片）與附件部分：

MimeMultipart mixed = new MimeMultipart("mixed");

// 內層：正文與圖片
MimeBodyPart contentPart = new MimeBodyPart();
contentPart.setContent(related); // 上方建立的 related multipart
mixed.addBodyPart(contentPart);

// 附件部分
MimeBodyPart attachment = new MimeBodyPart();
attachment.attachFile(new File("report.pdf"));
attachment.setFileName(MimeUtility.encodeText("報告.pdf"));
mixed.addBodyPart(attachment);

message.setContent(mixed);

進階技巧與最佳實踐

• 連接池化：生產環境建議使用 javax.mail.Session 搭配連接池（如 Apache Commons Pool）複用 SMTP 連接。
• 異步發送：結合 CompletableFuture 或消息隊列（RabbitMQ/Kafka）實現非阻塞郵件投遞。
• 模板引擎整合：引入 Thymeleaf 或 FreeMarker 分離郵件模板與業務邏輯。
• 彈性重試：針對網絡抖動實施指數退避重試策略，並記錄失敗郵件供人工介入。
• 安全加固：強制啟用 STARTTLS、驗證伺服器憑證、儲存憑證於密碼管理器而非明文配置。

常見問題排查

JavaMail API 雖然歷經歲月，但憑藉其標準化設計與靈活擴展性，仍是 Java 生態中處理郵件業務的首選方案。掌握其核心模型與實戰模式，能讓你輕松應對從簡單通知到複雜營銷郵件的各種場景。