高级 Gmail 服务

利用高级 Gmail 服务，您可以在 Apps 脚本中使用 Gmail API。与 Apps 脚本的内置 Gmail 服务非常相似，此 API 允许脚本在 Gmail 邮箱中查找和修改会话、邮件和标签。在大多数情况下，内置服务更易于使用，但高级服务提供了一些额外的功能，并且可以访问有关 Gmail 内容的更详细信息。

注意： 这是一项高级服务，必须先启用才能使用。

参考

如需详细了解此服务，请参阅 Gmail API 的参考文档。与 Apps 脚本中的所有高级服务一样，高级 Gmail 服务使用的对象、方法和参数均与公共 API 相同。如需了解详情，请参阅方法签名的确定方式。

注意： 为了提高性能，Gmail API 通常会限制 list 请求返回的信息量，仅返回线程、邮件或标签 ID 以及其他简单信息。如需获取有关特定会话、邮件或标签的更详细信息，请使用关联的 ID 发出后续 get 请求。

如需报告问题并查找其他支持，请参阅 Gmail 支持指南。

示例代码

以下示例代码使用 API 的版本 1。

列出标签信息

以下示例演示了如何列出所有用户的标签信息。包括标签名称、类型、ID 和公开范围设置。

advanced/gmail.gs

在 GitHub 上查看

/**
 * Lists the user's labels, including name, type,
 * ID and visibility information.
 */
function listLabelInfo() {
  try {
    const response = Gmail.Users.Labels.list("me");
    for (let i = 0; i < response.labels.length; i++) {
      const label = response.labels[i];
      console.log(JSON.stringify(label));
    }
  } catch (err) {
    console.log(err);
  }
}

列出收件箱摘要

以下示例演示了如何列出与用户收件箱中每个会话相关联的文本片段。请注意，您可以使用页面令牌来访问完整的结果列表。

advanced/gmail.gs

在 GitHub 上查看

/**
 * Lists, for each thread in the user's Inbox, a
 * snippet associated with that thread.
 */
function listInboxSnippets() {
  try {
    let pageToken;
    do {
      const threadList = Gmail.Users.Threads.list("me", {
        q: "label:inbox",
        pageToken: pageToken,
      });
      if (threadList.threads && threadList.threads.length > 0) {
        for (const thread of threadList.threads) {
          console.log(`Snippet: ${thread.snippet}`);
        }
      }
      pageToken = threadList.nextPageToken;
    } while (pageToken);
  } catch (err) {
    console.log(err);
  }
}

列出近期历史记录

以下示例演示了如何记录近期活动历史记录。 具体而言，此示例会恢复与用户最近发送的消息相关联的历史记录 ID，然后记录自那时起发生更改的每条消息的消息 ID。无论历史记录中有多少个更改事件，每个已更改的消息都只会记录一次。请注意，我们使用页面令牌来访问完整的结果列表。

advanced/gmail.gs

在 GitHub 上查看

/**
 * Gets a history record ID associated with the most
 * recently sent message, then logs all the message IDs
 * that have changed since that message was sent.
 */
function logRecentHistory() {
  try {
    // Get the history ID associated with the most recent
    // sent message.
    const sent = Gmail.Users.Threads.list("me", {
      q: "label:sent",
      maxResults: 1,
    });
    if (!sent.threads || !sent.threads[0]) {
      console.log("No sent threads found.");
      return;
    }
    const historyId = sent.threads[0].historyId;

    // Log the ID of each message changed since the most
    // recent message was sent.
    let pageToken;
    const changed = [];
    do {
      const recordList = Gmail.Users.History.list("me", {
        startHistoryId: historyId,
        pageToken: pageToken,
      });
      const history = recordList.history;
      if (history && history.length > 0) {
        for (const record of history) {
          for (const message of record.messages) {
            if (changed.indexOf(message.id) === -1) {
              changed.push(message.id);
            }
          }
        }
      }
      pageToken = recordList.nextPageToken;
    } while (pageToken);

    for (const id of changed) {
      console.log("Message Changed: %s", id);
    }
  } catch (err) {
    console.log(err);
  }
}

列出消息

以下示例演示了如何列出 Gmail 用户未读的邮件。

advanced/gmail.gs

在 GitHub 上查看

/**
 * Lists unread messages in the user's inbox using the advanced Gmail service.
 */
function listMessages() {
  // The special value 'me' indicates the authenticated user.
  const userId = "me";

  // Define optional parameters for the request.
  const options = {
    maxResults: 10, // Limit the number of messages returned.
    q: "is:unread", // Search for unread messages.
  };

  try {
    // Call the Gmail.Users.Messages.list method.
    const response = Gmail.Users.Messages.list(userId, options);
    const messages = response.messages;
    console.log("Unread Messages:");

    for (const message of messages) {
      console.log(`- Message ID: ${message.id}`);
    }
  } catch (err) {
    // Log any errors to the Apps Script execution log.
    console.log(`Failed with error: ${err.message}`);
  }
}