Email 類庫核心特性
- 多協議支援:mail()、Sendmail、SMTP (SSL/TLS)
- 多收件人:To、CC、BCC,支援批次模式
- 雙格式:HTML 與純文本替代內容
- 附件/內嵌圖片:多文件、CID 內嵌
- 自動換行/編碼:wordwrap、Base64/Quoted-Printable
- 優先級/標頭控制:Priority、自定義 Header
- 除錯工具:print_debugger() 顯示完整 SMTP 交互
快速入門:最簡發送
<?php
$this->load->library('email');
$this->email->from('sender@example.com', '發件人名稱');
$this->email->to('recipient@example.com');
$this->email->subject('測試郵件');
$this->email->message('這是一封測試郵件內容。');
if ($this->email->send()) {
echo '發送成功';
} else {
echo '發送失敗: ' . $this->email->print_debugger();
}
?>
完整配置選項 config/email.php
<?php
$config = [
'protocol' => 'smtp', // mail, sendmail, smtp
'smtp_host' => 'smtp.example.com',
'smtp_port' => 587, // 25/465/587/2525
'smtp_user' => 'user@example.com',
'smtp_pass' => 'password', // 應用專用密碼
'smtp_timeout' => 30,
'smtp_keepalive' => true, // 持久連接,批量發送提速
'smtp_crypto' => 'tls', // ssl, tls, '' (PHP 5.6+)
'charset' => 'utf-8',
'wordwrap' => true,
'wrapchars' => 76,
'mailtype' => 'html', // html 或 text
'validation' => true, // 驗證 email 格式
'priority' => 3, // 1 高, 3 正常, 5 低
'crlf' => "\r\n",
'newline' => "\r\n",
'bcc_batch_mode' => false, // true 時自動分批 BCC
'bcc_batch_size' => 200, // 每批 BCC 數量
'dsn' => false, // 狀態通知 (Delivery Status Notification)
];
?>
進階功能示範
1. HTML 郵件 + 純文本替代
$this->email->message($htmlContent);
$this->email->set_alt_message($textContent); // 非 HTML 客戶端顯示
2. 多收件人與抄送
$this->email->to(['a@ex.com', 'b@ex.com']); // 多個 To
$this->email->cc('manager@ex.com'); // 抄送
$this->email->bcc(['list1@ex.com', 'list2@ex.com']); // 密送(收件人互不見)
3. 自定義標頭
$this->email->set_header('X-Priority', '1');
$this->email->set_header('X-MSMail-Priority', 'High');
$this->email->set_header('List-Unsubscribe', '');
4. 請求讀取回執
$this->email->set_header('Disposition-Notification-To', 'sender@example.com');
$this->email->set_header('Return-Receipt-To', 'sender@example.com');
5. 除錯輸出
// 發送前預覽
echo $this->email->print_debugger(['headers', 'subject', 'body']);
// 發送後獲取除錯資訊
if (!$this->email->send()) {
$debug = $this->email->print_debugger(); // 含 SMTP 交互日誌
log_message('error', $debug);
}
常見 SMTP 服務商配置參考
| 服務商 | SMTP Host | Port | 加密 | 備註 |
| Gmail | smtp.gmail.com | 465 | SSL | 需開啟「低安全性應用」或使用應用專用密碼 |
| Gmail | smtp.gmail.com | 587 | TLS | 推薦 |
| Outlook/Office365 | smtp.office365.com | 587 | TLS | |
| QQ 郵箱 | smtp.qq.com | 465/587 | SSL/TLS | 需開啟 SMTP 服務獲取授權碼 |
| 163 郵箱 | smtp.163.com | 465/587 | SSL/TLS | 需開啟 SMTP 服務獲取授權碼 |
| SendGrid | smtp.sendgrid.net | 587 | TLS | 用戶名: apikey,密碼: API Key |
| Mailgun | smtp.mailgun.org | 587 | TLS | 用戶名: postmaster@domain |
| Amazon SES | email-smtp.region.amazonaws.com | 587 | TLS | 需 SMTP 憑證 |
效能優化與生產建議
- 使用 SMTP Keep-Alive:`$config['smtp_keepalive'] = true` 批量發送時複用連接,大幅降低延遲。
- BCC 批次模式:大量收件人時開啟 `$config['bcc_batch_mode'] = true`,CI 自動分批發送,保護隱私並避免單郵件過大被拒。
- 異步佇列發送:將郵件任務推入 Redis/RabbitMQ,由 Worker 進程消費發送,HTTP 請求秒級返回。
- 模板引擎分離:使用 CI View 或 Blade/Twig 渲染 HTML,內容與邏輯分離。
- 送達率優化:配置域名 SPF/DKIM/DMARC,使用專用 IP,監控退信率、投訴率。
錯誤代碼速查
| 現象 | 常見原因 | 排查步驟 |
| 無法連接 SMTP | 端口被防火牆攔截、主機名錯誤、SSL/TLS 不匹配 | telnet host port;檢查 smtp_crypto 設置;嘗試 openssl s_client |
| 認證失敗 (535) | 密碼錯誤、未啟用 SMTP、使用登錄密碼而非應用密碼 | 登錄郵箱 Web 端驗證;生成應用專用密碼 |
| 發件人被拒 (550/553) | from 地址與認證帳號不符、域名未驗證、SPF 失敗 | from 必須等於或為認證帳號子帳號;檢查 DNS SPF 記錄 |
| 郵件進垃圾箱 | 內容觸發規則、IP 信譽差、缺少認證記錄 | 測試 mail-tester.com;優化內容;配置 DKIM/DMARC |
| 中文亂碼 | charset 不一致、Subject 未編碼 | 確保 config charset=utf-8;CI 自動編碼 Subject,舊版需手動 =?UTF-8?B? |
總結
CodeIgniter Email 類庫提供了開箱即用的郵件發送能力,涵蓋從簡單通知到複雜營銷郵件的各種需求。掌握其配置選項、附件/內嵌處理、BCC 批次、除錯工具,並結合專業郵件服務商與異步佇列架構,即可構建穩定、高送達率的郵件系統。現代專案建議將發送邏輯封裝為 Service 類,配合介面定義便於測試與替換底層實現(SMTP vs API)。