Gmail API 設有用量限制，規定 API 方法的呼叫頻率。限制是以配額單位定義，這是代表 Gmail 資源用量的抽象測量單位。
Gmail API 配額
系統會強制執行兩種配額：
每分鐘每個雲端專案：這是指 Google Cloud 雲端專案在一分鐘內可使用的配額單位數。
每項專案每位使用者每分鐘：這是指任何特定使用者在雲端專案中可使用的配額單位數量。這項限制旨在協助您確保使用者用量分配公平。
下表詳細列出這些限制：
| 用量限制類型 | 限制 |
|---|---|
| 每項專案每分鐘 | 1,200,000 個配額單位 |
| 每位使用者每項專案每分鐘 | 6,000 個配額單位 |
如要瞭解如何處理限制錯誤，請參閱「解決錯誤」。
每日結算最低曝光次數門檻
這項「每個專案每日」限制定義了 Google Cloud 專案在 24 小時內可使用的配額單位數量上限，超過上限就會產生費用。
如果用量低於這個門檻，就不會產生額外費用，Google Cloud 帳戶也不會收到帳單。我們會在 2026 年稍晚提供完整的帳單詳細資料，並在任何異動生效前至少 90 天發送通知。
您無法要求提高這項每日門檻限制。
下表詳細說明限制：
| 門檻限制類型 | 限制 |
|---|---|
| 每個專案每天 | 8,000 萬個配額單位 |
詳情請參閱「Google Workspace standardized model for agent tools and APIs」。
每種方法的配額用量
每個要求消耗的配額單位數取決於呼叫的方法。下表列出各方法使用的配額單位：
| 方法 | 配額單位 |
|---|---|
drafts.create |
10 |
drafts.delete |
10 |
drafts.get |
20 |
drafts.list |
5 |
drafts.send |
100 |
drafts.update |
15 |
getProfile |
1 |
history.list |
2 |
labels.create |
5 |
labels.delete |
5 |
labels.get |
1 |
labels.list |
1 |
labels.update |
5 |
messages.attachments.get |
20 |
messages.batchDelete |
50 |
messages.batchModify |
50 |
messages.delete |
10 |
messages.get |
20 |
messages.import |
25 |
messages.insert |
25 |
messages.list |
5 |
messages.modify |
5 |
messages.send |
100 |
messages.trash |
20 |
messages.untrash |
5 |
settings.delegates.create |
100 |
settings.delegates.delete |
5 |
settings.delegates.get |
1 |
settings.delegates.list |
1 |
settings.filters.create |
5 |
settings.filters.delete |
5 |
settings.filters.get |
1 |
settings.filters.list |
1 |
settings.forwardingAddresses.create |
100 |
settings.forwardingAddresses.delete |
5 |
settings.forwardingAddresses.get |
1 |
settings.forwardingAddresses.list |
1 |
settings.getAutoForwarding |
1 |
settings.getImap |
1 |
settings.getPop |
1 |
settings.getVacation |
1 |
settings.sendAs.create |
100 |
settings.sendAs.delete |
5 |
settings.sendAs.get |
1 |
settings.sendAs.list |
1 |
settings.sendAs.update |
100 |
settings.sendAs.verify |
100 |
settings.updateAutoForwarding |
5 |
settings.updateImap |
5 |
settings.updatePop |
100 |
settings.updateVacation |
5 |
stop |
50 |
threads.delete |
20 |
threads.get |
40 |
threads.list |
10 |
threads.modify |
10 |
threads.trash |
20 |
threads.untrash |
10 |
watch |
100 |
使用 Gmail API 時，每封電子郵件訊息的收件者人數上限為 500 人。
解決時間配額錯誤
對於所有時間相關錯誤 (每 X 分鐘最多 N 個要求)，建議您的程式碼擷取例外狀況，並使用截斷指數輪詢，確保裝置不會產生過多負載。
指數輪詢是網路應用程式的標準錯誤處理策略。指數輪詢演算法會以指數方式重試要求，並將每次要求之間的等待時間逐漸增加至最大輪詢時間，如果要求仍未成功，請務必隨著時間增加要求之間的延遲時間，直到要求成功為止。
演算法範例
指數輪詢演算法會以指數方式重試要求，並將每次重試之間的等待時間逐漸增加至最大輪詢時間，例如：
- 對 Gmail API 提出要求。
- 如果要求失敗，請等待 1 +
random_number_milliseconds秒後再重試要求。 - 如果要求失敗，請等待 2 +
random_number_milliseconds秒後再重試要求。 - 如果要求失敗，請等待 4 +
random_number_milliseconds秒後再重試要求。 - 依此類推，時間上限為
maximum_backoff。 - 繼續等待和重試，直到重試次數達特定上限，但不再增加每次重試之間的等待時間。
其中：
- 等待時間為
min(((2^n)+random_number_milliseconds), maximum_backoff)，n會在每次疊代 (要求) 時增加 1。 random_number_milliseconds是小於或等於 1,000 的隨機毫秒數。這種設定有助於避免多個用戶端在特定情況下全部同步進行處理並同時重試，導致同步傳送每一波要求。random_number_milliseconds的值會在每次重試要求後重新計算。maximum_backoff通常是 32 或 64 秒，適合的值視用途而異。
用戶端達到 maximum_backoff 時間上限後，還是可以繼續重試，但接下來的重試工作就不需繼續增加輪詢時間。舉例來說，如果用戶端使用的 maximum_backoff 時間上限是 64 秒，達到這個值之後，用戶端就可以維持在每 64 秒重試一次的頻率。到了特定時間點後，用戶端應停止無限重試。
重試之間的等待時間和重試次數，應視用途及您的網路狀況而定。
定價
使用 Gmail API 的所有標準功能都不必額外付費。預計在 2026 年稍晚，超出配額要求限制將會產生費用，並計入您的 Google Cloud 帳單帳戶。詳情請參閱「Google Workspace standardized model for agent tools and APIs」。
申請提高配額
您可以依據專案的資源用量，要求調整配額。服務帳戶發出的 API 呼叫會視為使用單一帳戶。我們不保證一定能核准您提出的配額調整要求。如果配額調整要求會大幅提高配額值，可能需要較長時間才能通過核准。
並非所有專案的配額都相同。隨著您使用 Google Cloud 的時間越長，可能需要提高配額值。如果預期用量將大幅攀升，可以透過 Google Cloud 控制台的「配額與系統限制」頁面，主動要求調整配額。
如要進一步瞭解相關內容，請參閱下列資源：