PHP 使用 IMAP 協定獲取郵件完整實戰教程

前言

IMAP (Internet Message Access Protocol) 是郵件存取的標準協定，PHP 內建的 IMAP 擴展提供了豐富的郵件操作功能。本文將詳細介紹如何使用 PHP IMAP 模組連接郵箱、列出資料夾、搜尋與讀取郵件，並包含 Windows 與 Linux 環境的安裝配置指南。

核心功能實現

連接郵箱並列出所有資料夾

<?php
$host = '{imap.mail.yahoo.com:993/ssl}';
$user = 'user@yahoo.com';
$pass = 'password';

// 開啟 IMAP 連接
$inbox = imap_open($host, $user, $pass);

// 獲取所有資料夾列表
$mailboxes = imap_list($inbox, $host, '*');

// 移除主機前綴，僅保留資料夾名稱
$mailboxes = str_replace($host, '', $mailboxes);

print_r($mailboxes);

/* 輸出範例：
Array
(
    [0] => Bulk Mail
    [1] => Draft
    [2] => Inbox
    [3] => Sent
    [4] => Trash
)
*/

// 關閉連接
imap_close($inbox);
?>

重新開啟指定資料夾並搜尋郵件

<?php
// 重新開啟指定資料夾（如垃圾郵件箱）
imap_reopen($inbox, $host . 'Bulk Mail');

// 搜尋所有郵件
$emails = imap_search($inbox, 'ALL');

print_r($emails);

// 獲取特定郵件內容
if ($emails) {
    $latest_email = $emails[0];
    $overview = imap_fetch_overview($inbox, $latest_email, 0);
    $message = imap_fetchbody($inbox, $latest_email, 1);
    
    echo "主旨: " . $overview[0]->subject . "\n";
    echo "寄件者: " . $overview[0]->from . "\n";
    echo "內容: " . $message . "\n";
}
?>

常用搜尋條件

imap_search() 支援多種搜尋條件：

環境安裝配置指南

Windows 環境安裝 IMAP 擴展

1. 開啟 php.ini 檔案
2. 尋找 ;extension=php_imap.dll，移除前面的分號啟用
3. 若 ext 目錄下缺少 php_imap.dll，需從 PHP 官方下載對應版本放入
4. 重啟 Web 伺服器（Apache/Nginx/IIS）

Linux 環境編譯安裝 IMAP 擴展

# 安裝依賴套件 (Ubuntu/Debian)
sudo apt-get install libc-client-dev libkrb5-dev

# 編譯 PHP IMAP 擴展
cd /path/to/php/source/ext/imap
phpize
./configure --with-php-config=/usr/local/webserver/php/bin/php-config \
            --with-kerberos=/usr \
            --with-imap-ssl=/usr
make
make install

# 在 php.ini 中啟用
echo "extension=imap.so" >> /usr/local/webserver/php/etc/php.ini

# 重啟 PHP-FPM
service php-fpm restart

進階應用範例：郵件自動處理系統

<?php
class MailProcessor {
    private $connection;
    
    public function __construct($host, $user, $pass) {
        $this->connection = imap_open($host, $user, $pass);
        if (!$this->connection) {
            throw new Exception("IMAP 連接失敗: " . imap_last_error());
        }
    }
    
    public function getUnreadMails($folder = 'INBOX') {
        imap_reopen($this->connection, $folder);
        $emails = imap_search($this->connection, 'UNSEEN');
        
        $results = array();
        if ($emails) {
            foreach ($emails as $email_id) {
                $overview = imap_fetch_overview($this->connection, $email_id, 0);
                $structure = imap_fetchstructure($this->connection, $email_id);
                $body = $this->getMailBody($this->connection, $email_id, $structure);
                
                $results[] = array(
                    'id' => $email_id,
                    'subject' => $overview[0]->subject,
                    'from' => $overview[0]->from,
                    'date' => $overview[0]->date,
                    'body' => $body
                );
            }
        }
        return $results;
    }
    
    private function getMailBody($conn, $msg_id, $structure, $part = 1) {
        // 遞歸處理多部分郵件，提取 text/plain 或 text/html 內容
        // 實現略...
    }
    
    public function __destruct() {
        if ($this->connection) {
            imap_close($this->connection);
        }
    }
}

// 使用範例
$processor = new MailProcessor('{imap.gmail.com:993/imap/ssl}', 'user@gmail.com', 'password');
$unread_mails = $processor->getUnreadMails();
foreach ($unread_mails as $mail) {
    echo "處理郵件: {$mail['subject']}\n";
    // 業務邏輯處理...
}
?>

常見問題與解決方案

• 連接超時：檢查防火牆是否開放 993 端口，確認主機名稱正確
• 認證失敗：Gmail 等服務需啟用「不太安全的應用程式存取」或使用應用程式專用密碼
• 中文亂碼：使用 imap_mime_header_decode() 解碼主旨與寄件者資訊
• 大量郵件效能：分批處理，避免一次性載入過多郵件導致記憶體耗盡

總結

PHP IMAP 擴展提供了完整的郵件操作能力，配合適當的錯誤處理與編碼轉換，可構建功能強大的郵件自動化系統。本文涵蓋了從環境配置到核心功能實現的完整流程，可作為專案開發的快速參考指南。