仅按邮件正文过滤却命中主题内容的问题排查与解决

我使用exchangelib库访问Exchange服务器，实现了基于发件人、可选择性按主题/正文过滤Outlook邮件的功能。但遇到一个问题：仅按正文内容过滤时，主题包含关键词的邮件也会被纳入结果。

比如收件箱中有3封来自目标发件人的邮件：

• 主题：'AAA BBB' | 正文：'AAA BBB'
• 主题：'BBB' | 正文：'AAA'
• 主题：'AAA' | 正文：'BBB'

当我仅指定正文过滤关键词为'BBB'时，第2封邮件（正文不含'BBB'但主题含）也被筛选出来，但仅按主题过滤时功能正常。

我的简化代码如下：

from exchangelib import Account, Credentials, Q
from typing import Literal


class EmailClient:
    def __init__(self) -> None:
        self.receiver_email = "mymail@email.com"
        self.receiver_un = "username"
        self.receiver_pw = "password"

    def filter_inbox(self, 
                     sender_address: str,
                     required_subj_part: str = "",
                     required_body_part: str = "",
                     both_operator: Literal["or", "and"] = "or") -> None:

        subj_query = Q(subject__contains=required_subj_part)
        body_query = Q(body__contains=required_body_part)

        if required_subj_part and required_body_part:
            if both_operator == "or":
                query = subj_query | body_query
            elif both_operator == "and":
                query = subj_query & body_query
            else:
                raise ValueError("'both_operator' must be one of: 'or', 'and'")

        elif required_subj_part:
            query = subj_query

        elif required_body_part:
            query = body_query

        else:
            query = Q()

        account = Account(self.receiver_email, autodiscover=True, 
                          credentials=Credentials(self.receiver_un, self.receiver_pw))

        for item in account.inbox.filter(query, sender=sender_address):
            subject = item.subject
            body = item.body.strip()

            print(f"{subject=}")
            print(f"{body=}", end="\n\n")


if __name__ == "__main__":
    ec = EmailClient()
    body_filter = "BBB"

    ec.filter_inbox("sender@email.com", required_body_part=body_filter)

问题原因 #

核心原因是Exchange服务器的contains查询在处理空字符串时会匹配所有内容，部分Exchange环境中body__contains的索引可能包含主题内容（比如HTML邮件的标题标签），导致exchangelib的Q对象无法完全精确区分正文与主题的搜索范围。

解决方法 #

方法1：本地过滤（最可靠，避免服务器端索引问题） #

先获取所有目标发件人的邮件，在本地将HTML格式的正文转为纯文本后再过滤，确保仅检查正文内容。

首先安装依赖处理HTML转纯文本：

pip install beautifulsoup4

修改后的代码：

from exchangelib import Account, Credentials, Q
from typing import Literal
from bs4 import BeautifulSoup


class EmailClient:
    def __init__(self) -> None:
        self.receiver_email = "mymail@email.com"
        self.receiver_un = "username"
        self.receiver_pw = "password"

    @staticmethod
    def html_to_text(html_content: str) -> str:
        # 把HTML格式的邮件正文转为纯文本
        if not html_content:
            return ""
        soup = BeautifulSoup(html_content, "html.parser")
        return soup.get_text(strip=True)

    def filter_inbox(self, 
                     sender_address: str,
                     required_subj_part: str = "",
                     required_body_part: str = "",
                     both_operator: Literal["or", "and"] = "or") -> None:

        # 先拉取所有目标发件人的邮件
        account = Account(self.receiver_email, autodiscover=True, 
                          credentials=Credentials(self.receiver_un, self.receiver_pw))
        sender_query = Q(sender=sender_address)
        all_sender_emails = account.inbox.filter(sender_query)

        # 本地执行过滤逻辑
        filtered_emails = []
        for item in all_sender_emails:
            # 检查主题匹配
            subject_matches = required_subj_part in item.subject if required_subj_part else True
            # 转换正文为纯文本后检查匹配
            plain_body = self.html_to_text(item.body)
            body_matches = required_body_part in plain_body if required_body_part else True

            # 应用逻辑运算符
            if required_subj_part and required_body_part:
                if (both_operator == "or" and (subject_matches or body_matches)) or \
                   (both_operator == "and" and (subject_matches and body_matches)):
                    filtered_emails.append(item)
            elif required_subj_part and subject_matches:
                filtered_emails.append(item)
            elif required_body_part and body_matches:
                filtered_emails.append(item)
            else:
                filtered_emails.append(item)

        # 输出结果
        for item in filtered_emails:
            subject = item.subject
            plain_body = self.html_to_text(item.body)
            print(f"{subject=}")
            print(f"{plain_body=}", end="\n\n")


if __name__ == "__main__":
    ec = EmailClient()
    body_filter = "BBB"

    ec.filter_inbox("sender@email.com", required_body_part=body_filter)

方法2：使用Exchange原生查询语言（Raw Query） #

通过exchangelib的raw_query参数，直接使用Exchange原生搜索语法，精确指定仅搜索正文内容：

修改filter_inbox方法中的查询构造部分：

def filter_inbox(self, 
                 sender_address: str,
                 required_subj_part: str = "",
                 required_body_part: str = "",
                 both_operator: Literal["or", "and"] = "or") -> None:

    # 构建Exchange原生查询片段
    query_parts = [f"SenderEmailAddress:{sender_address}"]
    if required_subj_part:
        query_parts.append(f"Subject:{required_subj_part}")
    if required_body_part:
        query_parts.append(f"Body:{required_body_part}")

    # 拼接逻辑运算符
    if required_subj_part and required_body_part:
        operator = " OR " if both_operator == "or" else " AND "
        raw_query = operator.join(query_parts)
    elif query_parts:
        raw_query = " AND ".join(query_parts)
    else:
        raw_query = ""

    account = Account(self.receiver_email, autodiscover=True, 
                      credentials=Credentials(self.receiver_un, self.receiver_pw))

    for item in account.inbox.filter(raw_query=raw_query):
        subject = item.subject
        body = item.body.strip()
        print(f"{subject=}")
        print(f"{body=}", end="\n\n")

说明 #

• 本地过滤方法不受服务器端索引配置影响，能确保精确筛选正文内容，适合对过滤精度要求高的场景。
• 原生查询方法利用Exchange原生语法，查询效率更高，适合邮件数量较多的场景，但需要确保Exchange服务器支持该语法。

内容的提问来源于stack exchange，提问作者Itay Dvash