C# 實作 SMTP 郵件發送完整類別庫

前言

在 .NET 應用程式開發中，郵件發送功能幾乎是標準配備。雖然 .NET Framework 內建 System.Net.Mail.SmtpClient 提供基本功能，但在某些特殊場景下（如需要精確控制 SMTP 協議流程、支援特定認證機制、或是在不支援高階 API 的舊版環境中），自行實作底層 SMTP 通訊類別反而更具彈性。本文介紹一個完整的 C# SMTP 郵件發送類別 KSN_Smtp，支援多種認證模式、附件處理、HTML/純文字郵件格式，並內建詳細的錯誤碼對照與日誌記錄功能。

核心架構設計

郵件訊息封裝：MailMessage 類別

MailMessage 類別負責封裝郵件的所有屬性，包含寄件人、收件人集合、主旨、郵件編碼（GB2312、ASCII、Unicode、UTF8）、郵件格式（HTML/純文字）、附件清單與郵件內容位元組陣列。採用 StringCollection 管理多收件人與多附件，設計直觀易用。

SMTP 認證模式支援

類別定義 SmtpValidateTypes 列舉，支援四種認證方式：

• None：無需認證，直接發送
• Login：標準 AUTH LOGIN 機制，帳號密碼分別 Base64 編碼傳輸
• Plain：AUTH PLAIN 機制，將 \0username\0password 整體 Base64 編碼
• CRAMMD5：CRAM-MD5 挑戰回應機制，透過 HMAC-MD5 計算回應碼，安全性較高

關鍵技術實作細節

SMTP 協議流程控制

KSN_Smtp 以 TcpClient 與 NetworkStream 建立 TCP 連線，手動實作 SMTP 指令交互流程：

1. 連線建立後讀取伺服器 220 歡迎訊息
2. 發送 HELO/EHLO 問候
3. 依選定認證模式執行驗證流程
4. 發送 MAIL FROM、RCPT TO 指定寄收件人
5. 發送 DATA 進入郵件內容傳輸階段
6. 組裝 MIME 郵件內容（含多部分替代、附件編碼）
7. 以 .\r\n 結束資料傳輸，發送 QUIT 斷線

每個指令發送後皆讀取伺服器回應碼，透過內建 errorCodes 與 rightCodes 字典判斷執行成敗，異常時拋出 ApplicationException 並記錄詳細錯誤訊息。

MIME 郵件組裝邏輯

SendMail 方法根據是否有附件、郵件格式（HTML/文字）動態組裝 MIME 結構：

• 無附件、純文字：Content-Type: text/plain + Base64 編碼內文
• 無附件、HTML：multipart/alternative 邊界分隔，僅包含 HTML 部分
• 有附件、純文字：multipart/mixed 包含文字內文與多個附件部分
• 有附件、HTML：multipart/mixed 包含 HTML 內文與附件，附件採用 application/octet-stream + Content-Disposition: attachment

所有非 ASCII 內容（主旨、內文、附件檔名）均依指定編碼（預設 GB2312）轉 Base64，確保中文相容性。

非同步資料傳輸與日誌記錄

郵件資料傳輸階段採用 NetworkStream.BeginWrite 非同步寫入，搭配 asyncCallBack 回呼確認完成。完整通訊過程（指令、回應、錯誤）皆記錄於 logs 字串，支援輸出至指定路徑（LogPath），編碼為 GB2312，便於事後除錯審計。

使用範例

var smtp = new KSN_Smtp("smtp.example.com", 25)
{
    UserID = "user@example.com",
    Password = "password",
    SmtpValidateType = SmtpValidateTypes.Login,
    LogPath = @"C:\Logs\smtp.log"
};

var mail = new MailMessage
{
    Sender = "user@example.com",
    Subject = "測試郵件",
    XMailer = "KSN_Smtp v1.0",
    MailEncoding = MailEncodings.UTF8,
    MailType = MailTypes.Html,
    MailBody = Encoding.UTF8.GetBytes("<h1>Hello World</h1>")
};
mail.Receivers.Add("recipient@example.com");
mail.Attachments.Add(@"C:\Files\report.pdf");

bool success = smtp.SendMail(mail);
if (!success) Console.WriteLine("發送失敗：" + smtp.ErrorMessage);

適用場景與注意事項

• 需精確控制 SMTP 協議細節（如特定伺服器非標準行為）
• 舊版 .NET Framework / .NET Compact Framework 環境
• 教學用途：理解 SMTP 協議、MIME 結構、Base64 編碼、非同步 Socket 程式設計
• 注意：現代應用建議優先使用 System.Net.Mail.SmtpClient 或 MailKit 等成熟函式庫，支援 SSL/TLS、OAuth2、DKIM 簽章等企業級功能；本類別未內建 SSL/TLS 支援，若需加密傳輸需自行在 NetworkStream 上層包裝 SslStream。

原始碼結構概覽