如何通过Gmail API获取并以列表形式展示邮件

你当前使用的快速入门代码权限配置（gmail.readonly 作用域）已经满足邮件读取需求，不需要调整授权相关逻辑，只需要替换原有拉取标签的业务代码即可。

Gmail API 获取邮件列表分两个步骤：

• 调用消息列表接口，获取指定范围的邮件ID列表（该接口不返回邮件标题、发件人等具体内容）
• 根据拿到的邮件ID，调用消息详情接口拉取需要展示的邮件字段

具体修改步骤 #

1. 找到handleAuthClick方法内授权成功后的逻辑，把原来的await listLabels();替换为await listMessages();
2. 删除原有的listLabels函数，替换为下面的邮件列表拉取代码：

async function listMessages() {
  let listRes;
  try {
    // 拉取收件箱最新20封邮件的ID列表
    listRes = await gapi.client.gmail.users.messages.list({
      userId: 'me',
      maxResults: 20, // 单次拉取数量可按需调整，最大支持500
      labelIds: ['INBOX'] // 仅拉取收件箱邮件，移除该参数可拉取所有邮件
    });
  } catch (err) {
    document.getElementById('content').innerText = err.message;
    return;
  }

  const messages = listRes.result.messages;
  if (!messages || messages.length === 0) {
    document.getElementById('content').innerText = '未查询到邮件';
    return;
  }

  const outputLines = ['收件箱邮件列表：\n'];
  // 逐个拉取邮件详情
  for (const msgItem of messages) {
    try {
      const detailRes = await gapi.client.gmail.users.messages.get({
        userId: 'me',
        id: msgItem.id,
        format: 'metadata', // 仅拉取指定头信息，加载速度更快
        metadataHeaders: ['Subject', 'From', 'Date'] // 指定需要的字段：主题、发件人、发送时间
      });
      const headers = detailRes.result.payload.headers;
      const subject = headers.find(h => h.name === 'Subject')?.value || '(无主题)';
      const sender = headers.find(h => h.name === 'From')?.value || '(未知发件人)';
      const sendTime = headers.find(h => h.name === 'Date')?.value || '';
      outputLines.push(`【主题】${subject}\n【发件人】${sender}\n【时间】${sendTime}\n---`);
    } catch (err) {
      outputLines.push(`邮件 ${msgItem.id} 加载失败：${err.message}\n---`);
    }
  }

  document.getElementById('content').innerText = outputLines.join('\n');
}

常用扩展说明 #

• 分页加载：messages.list接口返回结果如果携带nextPageToken字段，下次调用时把该值传入pageToken参数，即可拉取下一页邮件
• 切换文件夹：修改labelIds参数的值即可拉取不同文件夹的邮件，比如已发送邮件传['SENT']、草稿传['DRAFTS']，也可以传入你之前通过标签接口拿到的自定义标签ID
• 性能优化：如果单次拉取邮件数量较多，可以使用gapi的批量请求能力，把多个邮件详情请求合并为一次HTTP请求，减少加载耗时
• 读取正文：需要展示邮件正文时，把messages.get的format参数改为full，从返回结果的payload.parts字段中解析对应编码的文本/HTML内容即可

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