基于Sheets与Gmail API的批量邮件工具速率限制问题求助

阿华AIGC实验室

2026-5-19

解决Gmail API批量发送邮件的速率限制问题

Hey Tyler, 这个问题我之前帮朋友踩过坑，Gmail API的速率限制确实容易在批量发送时触发，尤其是你现在先把所有邮件构建好再一次性遍历发送的方式，短时间内请求太密集了。咱们一步步来解决：

为什么会触发"速率限制超出"？

Gmail API的限制不止有每日发送配额（比如个人账号每天100封），还有短期的请求频率限制（比如每分钟最多10-15次发送请求）。你一次性连续发7封后触发限制，就是因为短时间内的请求量超过了这个高频阈值。

具体解决方案

1. 给发送请求添加延迟（最容易实现）

在每发送一封邮件后，让程序等待几秒，把请求分散开，避免短时间内挤爆API的频率限制。比如等待2-5秒就足够缓解大部分情况。

举个Python的代码例子：

import time
from googleapiclient.discovery import build

# 假设你已经初始化好Gmail API的service对象，以及构建好的邮件列表emails
for email in emails:
    # 执行发送操作
    service.users().messages().send(userId='me', body=email).execute()
    # 等待3秒再发下一封，时间可以根据实际情况调整
    time.sleep(3)

2. 实现重试机制，处理配额超限

当收到429（速率限制）错误时，不要直接放弃，应该根据API返回的Retry-After头信息（如果有的话）等待指定时间后重试，最多重试几次避免死循环。

示例代码：

import time
from googleapiclient.errors import HttpError

for email in emails:
    max_retries = 3
    current_retry = 0
    success = False
    
    while current_retry < max_retries:
        try:
            service.users().messages().send(userId='me', body=email).execute()
            success = True
            break
        except HttpError as err:
            if err.resp.status == 429:
                # 提取建议等待的时间，没有的话默认等5秒
                wait_time = int(err.resp.headers.get('Retry-After', 5))
                print(f"触发速率限制，等待{wait_time}秒后重试...")
                time.sleep(wait_time)
                current_retry += 1
            else:
                # 其他类型的错误直接抛出，按需处理
                raise
    
    if not success:
        print(f"邮件发送失败，已重试{max_retries}次: {email}")

3. 使用批量请求减少HTTP请求数

Gmail API支持批量请求，把多个发送操作打包成一个HTTP请求，能有效减少请求频率。不过要注意，一个批量请求最多包含100个操作，而且发送完一批后还是要适当等待。

示例代码：

from googleapiclient.http import BatchHttpRequest
import time

def send_callback(request_id, response, exception):
    if exception:
        print(f"发送失败: {str(exception)}")
    else:
        print(f"邮件发送成功，ID: {response['id']}")

# 分批次处理邮件，每批10封
batch_size = 10
for i in range(0, len(emails), batch_size):
    batch = BatchHttpRequest(callback=send_callback)
    # 把当前批次的邮件加入批量请求
    for email in emails[i:i+batch_size]:
        batch.add(service.users().messages().send(userId='me', body=email))
    # 执行批量发送
    batch.execute()
    # 每批发送完等待10秒
    time.sleep(10)