萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> 程式語言綜合

Python SMTP 發送 QQ 郵件完整實作:SSL/TLS、附件、異常處理與安全最佳實踐

QQ 郵箱 SMTP 設定

核心程式碼:支援純文本、HTML、附件、多收件人


#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
QQ 郵件發送模組
支援:純文本/HTML、多收件人、附件、SSL/TLS、重試、日誌
"""
import smtplib
import ssl
import logging
import mimetypes
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart
from email.mime.base import MIMEBase
from email.mime.application import MIMEApplication
from email.header import Header
from email.utils import formataddr, make_msgid
from typing import List, Optional, Tuple, BinaryIO
from pathlib import Path

logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
logger = logging.getLogger(__name__)

class QQMailSender:
    def __init__(self, username: str, auth_code: str, 
                 host: str = 'smtp.qq.com', port: int = 465, use_ssl: bool = True,
                 timeout: int = 30):
        """
        :param username: QQ 號碼 (不含 @qq.com)
        :param auth_code: 授權碼 (16 位字元)
        :param use_ssl: True=SSL (465), False=STARTTLS (587)
        """
        self.username = username
        self.auth_code = auth_code
        self.host = host
        self.port = port
        self.use_ssl = use_ssl
        self.timeout = timeout
        self.from_addr = f'{username}@qq.com'
    
    def _create_connection(self) -> smtplib.SMTP:
        """建立 SMTP 連線"""
        context = ssl.create_default_context()
        if self.use_ssl:
            # 隱含 SSL
            conn = smtplib.SMTP_SSL(self.host, self.port, context=context, timeout=self.timeout)
        else:
            # STARTTLS
            conn = smtplib.SMTP(self.host, self.port, timeout=self.timeout)
            conn.ehlo()
            conn.starttls(context=context)
            conn.ehlo()
        return conn
    
    def _build_message(self, to_addrs: List[str], subject: str, 
                       body: str, is_html: bool = False,
                       attachments: Optional[List[Tuple[str, bytes]]] = None,
                       cc: Optional[List[str]] = None,
                       bcc: Optional[List[str]] = None) -> MIMEMultipart:
        """建構 MIME 郵件"""
        msg = MIMEMultipart('mixed')
        msg['Message-ID'] = make_msgid(domain='qq.com')
        msg['From'] = formataddr(('Python Sender', self.from_addr))
        msg['To'] = ', '.join(to_addrs)
        if cc:
            msg['Cc'] = ', '.join(cc)
        # Bcc 不寫入標頭
        msg['Subject'] = Header(subject, 'utf-8')
        
        # 郵件本體
        body_part = MIMEText(body, 'html' if is_html else 'plain', 'utf-8')
        msg.attach(body_part)
        
        # 附件
        if attachments:
            for filename, content in attachments:
                part = MIMEApplication(content, Name=filename)
                part['Content-Disposition'] = f'attachment; filename="{filename}"'
                part['Content-ID'] = f'<{make_msgid(domain="attachment")}>'
                msg.attach(part)
        
        return msg
    
    def send(self, to_addrs: List[str], subject: str, body: str,
             is_html: bool = False,
             attachments: Optional[List[Tuple[str, bytes]]] = None,
             cc: Optional[List[str]] = None,
             bcc: Optional[List[str]] = None,
             max_retries: int = 3) -> bool:
        """
        發送郵件
        :return: 成功 True / 失敗 False
        """
        all_recipients = list(to_addrs)
        if cc: all_recipients.extend(cc)
        if bcc: all_recipients.extend(bcc)
        
        msg = self._build_message(to_addrs, subject, body, is_html, attachments, cc, bcc)
        
        for attempt in range(1, max_retries + 1):
            try:
                with self._create_connection() as conn:
                    conn.login(self.username, self.auth_code)
                    conn.sendmail(self.from_addr, all_recipients, msg.as_string())
                    logger.info(f"郵件發送成功: {subject} → {to_addrs} (嘗試 {attempt}/{max_retries})")
                    return True
            except smtplib.SMTPAuthenticationError as e:
                logger.error(f"認證失敗: {e} (檢查授權碼、是否開啟 SMTP 服務)")
                return False  # 認證錯誤不重試
            except (smtplib.SMTPConnectError, smtplib.SMTPServerDisconnected, 
                    ConnectionResetError, TimeoutError, ssl.SSLError) as e:
                logger.warning(f"網路錯誤 (嘗試 {attempt}/{max_retries}): {e}")
                if attempt == max_retries:
                    logger.error("達到最大重試次數,發送失敗")
                    return False
            except smtplib.SMTPException as e:
                logger.error(f"SMTP 協議錯誤: {e}")
                return False
            except Exception as e:
                logger.exception(f"未預期錯誤: {e}")
                return False
        return False

# === 使用範例 ===
if __name__ == '__main__':
    # 從環境變數讀取敏感資訊 (勿硬編碼!)
    import os
    QQ_USER = os.getenv('QQ_MAIL_USER')      # 你的 QQ 號
    QQ_AUTH = os.getenv('QQ_MAIL_AUTH_CODE') # 授權碼
    
    if not QQ_USER or not QQ_AUTH:
        print("請設定環境變數 QQ_MAIL_USER 和 QQ_MAIL_AUTH_CODE")
        exit(1)
    
    sender = QQMailSender(QQ_USER, QQ_AUTH, use_ssl=True)
    
    # 簡單文字郵件
    ok = sender.send(
        to_addrs=['recipient1@qq.com', 'recipient2@gmail.com'],
        subject='Python 測試郵件',
        body='這是一封由 Python 發送的測試郵件。\n包含中文內容。',
        is_html=False
    )
    
    # HTML 郵件 + 附件
    html_body = """
    
    

HTML 郵件測試

支援 粗體、斜體、連結。

參數值
SMTP 伺服器smtp.qq.com
SSL 埠465 (隱含 SSL)
TLS/STARTTLS 埠587 (明文啟動 TLS)
帳號QQ 號碼 (如 123456789)
密碼授權碼 (非 QQ 登入密碼,需在網頁版設定 → 帳號 → 開啟 SMTP 服務獲取)
欄位值
狀態成功
""" # 讀取附件 attachments = [] for fname in ['report.pdf', 'data.csv']: if Path(fname).exists(): attachments.append((fname, Path(fname).read_bytes())) ok = sender.send( to_addrs=['team@example.com'], subject='每日自動報表', body=html_body, is_html=True, attachments=attachments, cc=['manager@example.com'] ) print("發送結果:", "成功" if ok else "失敗")

關鍵安全與可靠性要點

風險對策
密碼洩漏使用授權碼而非登入密碼;從環境變數/金鑰管理系統讀取;禁止硬編碼
中間人攻擊強制使用 SSL/TLS (port 465 或 587+STARTTLS);驗證伺服器憑證
郵件偽造設定 SPF、DKIM、DMARC 記錄 (域名持有者端)
大量發送被封控制頻率、使用郵件隊列、遵守 QQ 郵箱發送限制 (每日/小時額度)
附件惡意代碼掃描附件、限制副檔名、檔案大小上限

常見錯誤排查

  • 535 Error: authentication failed → 授權碼錯誤、未開啟 SMTP 服務、帳號異常
  • Connection timed out → 防火牆攔截、埠號錯誤、網路不通、雲服務商封鎖 465/587
  • 550 Mail content denied → 內容觸發反垃圾郵件規則 (關鍵字、連結、附件類型)
  • ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] → 系統 CA 憑證舊、需更新 certifi 或信任 QQ 憑證鏈

總結

Python 發送 QQ 郵件核心是:授權碼認證 + SSL/TLS 加密 + 標準 MIME 組裝 + 完善異常處理。封裝可重用類別,配合環境變數管理密鑰、重試機制、結構化日誌,即可構建生產級郵件發送服務。

copyright © 萬盛學電腦網 all rights reserved