Gmail API高级筛选：如何获取与指定用户的往来邮件列表

之前筛选逻辑卡壳，本质是没搞透Gmail搜索语法的逻辑优先级——直接拼多段带OR的条件不做块包裹，解析出来的规则和预期完全不一样。

核心查询逻辑构造 #

要同时满足“双向覆盖”“排除聊天内容”的筛选要求，不需要拆分多次拉取收件箱、已发箱的结果做本地合并，直接构造带正确优先级的查询语句即可：

• 双向匹配规则拆分：
  • 匹配对方发来的邮件：所有满足from:指定联系人邮箱的消息
  • 匹配你发出的邮件：所有满足to:指定联系人邮箱的消息
• 全局过滤规则：所有匹配结果全局排除聊天类消息，对应-in:chats
• 优先级处理注意点：Gmail语法里AND的判断优先级高于OR，所有带OR的并列匹配块必须用括号包裹，不然会出现条件串味——比如直接写-in:chats from:user1 OR to:user1，实际执行逻辑是“（排除聊天且来自user1的邮件） OR （所有发给user1的消息，不管是不是聊天内容）”，和预期的双向过滤完全不符。

可直接复用的代码实现 #

如果目标联系人是user1@gmail.com、user2@gmail.com，最终拼接出的查询语句为：

(-in:chats) AND ((from:user1@gmail.com OR from:user2@gmail.com) OR (to:user1@gmail.com OR to:user2@gmail.com))

对应的可扩展Java代码实现如下：

public List<Message> getMessagesWithSpecifiedContacts(Gmail service, List<String> targetContactEmails) throws IOException {
    // 拼接所有目标联系人的发件人匹配规则
    String fromMatchBlock = targetContactEmails.stream()
            .map(email -> "from:" + email)
            .collect(Collectors.joining(" OR "));
    // 拼接所有目标联系人的收件人匹配规则
    String toMatchBlock = targetContactEmails.stream()
            .map(email -> "to:" + email)
            .collect(Collectors.joining(" OR "));
    // 组装带正确优先级的完整查询语句
    String query = String.format("(-in:chats) AND ((%s) OR (%s))", fromMatchBlock, toMatchBlock);
    // 分页拉取全量结果，避免默认单页100条的限制导致数据不全
    List<Message> fullMessages = new ArrayList<>();
    String nextPageToken = null;
    do {
        ListMessagesResponse queryResult = service.users().messages().list("me")
                .setQ(query)
                .setPageToken(nextPageToken)
                .execute();
        fullMessages.addAll(queryResult.getMessages());
        nextPageToken = queryResult.getNextPageToken();
    } while (nextPageToken != null);
    return fullMessages;
}

补充注意事项 #

• 如果业务强制要求仅在收件箱、已发箱两个位置取数，不需要覆盖其他手动归档的文件夹，可以在查询语句里叠加位置限制，调整后query结构为：

  (-in:chats) AND (in:inbox OR in:sent) AND ((from匹配块) OR (to匹配块))
  

  同样要注意所有逻辑块用括号包裹，避免解析逻辑出错。
• 如果遇到部分邮件匹配不准的情况，可以在拉取消息列表后，对单条消息的邮件头做二次校验，核对From/To字段是否在目标联系人列表内，减少因为发件人别名、伪造头带来的匹配误差。

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