Google Script处理Gmail：标记单条邮件+避免重复解析交易邮件

算力阿峰

2026-5-9

解决Google Script中标记单条Gmail邮件及避免重复处理的问题

一、如何标记并检查仅单条Gmail邮件？

Gmail默认的GmailApp类主要围绕线程（Thread）操作，但要单独处理单条消息（Message），就得用到Gmail API（需要先在脚本编辑器里启用）。具体步骤如下：

启用Gmail API：在Google Script编辑器中，点击「扩展」→「Apps脚本」→「服务」，找到Gmail API并启用。
标记单条消息：使用Gmail.Users.Messages.modify()方法给指定消息ID添加自定义标签。
检查消息是否已标记：通过Gmail.Users.Messages.get()获取消息的标签列表，判断是否包含目标标签ID。

示例代码片段：

// 给单条消息添加标签
function labelSingleMessage(messageId, labelId) {
  Gmail.Users.Messages.modify({
    addLabelIds: [labelId]
  }, "me", messageId);
}

// 检查单条消息是否带有指定标签
function isMessageLabeled(messageId, labelId) {
  const msg = Gmail.Users.Messages.get("me", messageId, {
    format: "metadata"
  });
  return msg.labelIds.includes(labelId);
}

二、处理指定标签下的银行交易邮件，避免重复/遗漏

你担心的线程重复处理、遗漏新消息的问题，核心解决方案就是针对单条消息而非线程进行标记和检查。下面是完整的实现思路和代码：

核心思路

创建一个自定义标签（比如ProcessedTransaction），专门标记已处理的单条交易消息。
通过Gmail API获取目标标签（比如BankTransactions）下的所有单条消息（而非线程）。
遍历每条消息，检查是否已标记ProcessedTransaction：未标记则处理，处理完成后添加标签；已标记则跳过。

完整代码实现

function processBankTransactions() {
  // 自定义标签：标记已处理的单条交易消息
  const processedLabelName = "ProcessedTransaction";
  // 你的银行交易邮件所在的目标标签
  const targetLabelName = "BankTransactions";

  // 获取或创建已处理标签
  let processedLabel = GmailApp.getUserLabelByName(processedLabelName);
  if (!processedLabel) {
    processedLabel = GmailApp.createLabel(processedLabelName);
  }
  const processedLabelId = processedLabel.getId();

  // 获取目标标签（确保已存在）
  const targetLabel = GmailApp.getUserLabelByName(targetLabelName);
  if (!targetLabel) {
    console.log("错误：目标标签「" + targetLabelName + "」不存在，请先创建！");
    return;
  }
  const targetLabelId = targetLabel.getId();

  // 使用Gmail API获取目标标签下的所有单条消息
  const messageList = Gmail.Users.Messages.list("me", {
    labelIds: [targetLabelId],
    maxResults: 100 // 可根据邮件数量调整，批量处理
  });

  if (!messageList.messages) {
    console.log("没有待处理的银行交易邮件");
    return;
  }

  // 遍历每条消息进行处理
  messageList.messages.forEach(msg => {
    const messageId = msg.id;
    // 获取消息的标签信息，判断是否已处理
    const messageDetails = Gmail.Users.Messages.get("me", messageId, {
      format: "metadata",
      metadataHeaders: ["Subject"] // 仅获取主题，减少数据量
    });

    const isAlreadyProcessed = messageDetails.labelIds.includes(processedLabelId);
    if (!isAlreadyProcessed) {
      // --------------------------
      // 这里写你的交易解析逻辑
      // 比如提取邮件内容中的交易金额、时间等
      const subject = messageDetails.payload.headers.find(h => h.name === "Subject").value;
      console.log("正在处理交易邮件：" + subject);
      // --------------------------

      // 标记这条消息为已处理
      Gmail.Users.Messages.modify({
        addLabelIds: [processedLabelId]
      }, "me", messageId);

      // 可选：如果不需要再在目标标签中显示已处理邮件，可以移除目标标签
      // Gmail.Users.Messages.modify({
      //   removeLabelIds: [targetLabelId]
      // }, "me", messageId);
    } else {
      console.log("邮件「" + messageDetails.payload.headers.find(h => h.name === "Subject").value + "」已处理，跳过");
    }
  });
}

关键优势

避免重复处理：每条消息单独标记，即使同一线程有多条相同主题的邮件，也只会处理未标记的消息。
不会遗漏新消息：每次运行脚本都会获取目标标签下的所有单条消息，包括线程中新增的消息。
无需外部存储：所有状态都通过Gmail标签管理，不用额外维护消息ID列表。

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