如何通过一次API调用获取多个邮箱的GMAIL消息？

问题背景 #

已实现单个邮箱（user1@mydomain.com）的消息获取逻辑，但需要扩展到100+个邮箱，避免逐个循环调用的低效方式。原代码如下：

let client = new google.auth.JWT({
  email: "SERVICE_ACCOUNT_EMAIL", 
  key: "SERVICE_ACCOUNT_KEY",
  scopes: SCOPES,
  subject: 'user1@mydomain.com' // 需要替换为目标邮箱列表
});

const msgs = await google.gmail('v1').users.messages.list({
  auth: client,
  userId: 'me',
  maxResults: 1,
  q:"is:unread"
});

优化方案：带并发控制的批量请求 #

直接并发100+请求容易触发API限流，建议通过并发数控制实现高效批量获取，同时保证稳定性。

1. 封装单邮箱消息获取函数

为每个邮箱生成独立的授权客户端并执行请求，同时处理错误：

async function fetchEmailsForUser(targetEmail) {
  // 为每个目标邮箱创建独立的JWT授权客户端
  const client = new google.auth.JWT({
    email: "SERVICE_ACCOUNT_EMAIL", 
    key: "SERVICE_ACCOUNT_KEY",
    scopes: SCOPES,
    subject: targetEmail
  });

  try {
    await client.authorize(); // 完成授权
    const response = await google.gmail('v1').users.messages.list({
      auth: client,
      userId: 'me',
      maxResults: 1,
      q: "is:unread"
    });
    return { email: targetEmail, messages: response.data.messages || [] };
  } catch (error) {
    // 捕获单个请求的错误，不中断批量任务
    return { email: targetEmail, error: error.message };
  }
}

2. 控制并发数执行批量任务

使用第三方库p-limit（需先安装：npm install p-limit）限制并发请求数，避免触发限流：

const pLimit = require('p-limit');
// 限制同时执行的请求数，建议设为10-20，可根据API配额调整
const concurrencyLimit = pLimit(15);

// 目标邮箱列表
const targetEmails = [
  'user1@mydomain.com',
  'user2@mydomain.com',
  'user3@mydomain.com',
  // ... 其他100+个邮箱
];

// 生成带并发限制的任务队列
const batchTasks = targetEmails.map(email => concurrencyLimit(() => fetchEmailsForUser(email)));

// 执行所有任务，确保单个失败不影响全局
const results = await Promise.allSettled(batchTasks);

// 处理结果
results.forEach(result => {
  if (result.status === 'fulfilled') {
    const { email, messages } = result.value;
    console.log(`邮箱 ${email} 的未读消息:`, messages);
  } else {
    console.error(`获取邮箱失败:`, result.reason);
  }
});

关键注意事项 #

• API配额限制：Gmail API对每个被 impersonate的用户有每日调用配额（默认15000次/天），100+用户的单次请求不会触发配额耗尽，但如果有后续批量操作需提前确认配额。
• 并发数调整：根据Google API的限流策略，将并发数控制在10-20之间最优，过高的并发可能导致临时封禁或请求失败。
• 错误隔离：使用Promise.allSettled替代Promise.all，确保单个邮箱的请求失败不会中断整个批量任务，便于后续排查处理异常邮箱。
• 客户端复用：若同一邮箱需多次请求，可缓存已授权的JWT客户端减少重复授权开销，但针对100+不同邮箱，每个用户需独立客户端，开销可忽略。

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