Gmail API 設有用量限制，會限制呼叫 API 方法的頻率。限制是以配額單位定義，這是代表 Gmail 資源用量的抽象測量單位。
Gmail API 配額
Gmail API 會強制執行兩種配額：
每分鐘/每項專案：這是 Google Cloud 專案一分鐘內可使用的配額單位數量。
每項專案每位使用者每分鐘：這是任何一位使用者在雲端專案中可使用的配額單位數量。這項限制有助於確保使用者公平分配用量。
下表詳細列出這些限制：
| 用量限制類型 | 限制 |
|---|---|
| 每項專案每分鐘 | 1,200,000 個配額單位 |
| 每位使用者每項專案每分鐘 | 6,000 個配額單位 |
如要瞭解如何處理限制錯誤，請參閱「解決錯誤」。
每日結算最低曝光次數門檻
這項「每日每項專案」限制，定義了 Google Cloud 專案在 24 小時內可使用的配額單位上限，超過上限就會產生費用。
用量低於這個門檻不會產生額外費用，您的 Google Cloud 帳戶也不會產生帳單。Google 將於 2026 年稍晚提供完整的帳單詳細資料，並在任何異動生效前至少 90 天通知。
您無法要求提高這項每日門檻限制。
下表詳細列出限制：
| 門檻限制類型 | 限制 |
|---|---|
| 每項專案每天 | 80,000,000 個配額單位 |
詳情請參閱「Google Workspace 標準化模型：代理工具和 API」。
各方法的配額用量
每項要求耗用的配額單位數量，取決於您呼叫的方法和查詢參數。下表列出各方法的配額單位用量：
| 方法 | 配額單位 |
|---|---|
drafts.create |
10 |
drafts.delete |
10 |
drafts.get |
20 (如果 format 為 full、raw 或 html，則為 60) |
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 (如果 format 為 full、raw 或 html，則為 60) |
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 (如果 format 為 full，則為 120) |
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 標準化模型：代理工具和 API」。
申請提高配額
視專案的資源用量而定，您可能需要要求調整配額。服務帳戶發出的 API 呼叫會視為使用單一帳戶。我們不保證一定能核准您提出的配額調整要求。如果配額調整要求會大幅提高配額值，可能需要較長時間才能獲得核准。
並非所有專案的配額都相同。隨著 Google Cloud 用量增加，您可能需要提高配額。如果您預期使用量將大幅攀升，可以透過 Google Cloud 控制台的「配額與系統限制」頁面，主動提出配額調整要求。
如要進一步瞭解相關內容，請參閱下列資源：
Gmail MCP 伺服器配額
Gmail MCP 伺服器會使用查詢成本分配指標。下表依部分詳細列出各 Gmail MCP 伺服器方法的查詢費用：
Gmail MCP 配額
伺服器會強制執行兩種配額：
每分鐘每項專案：這是 Cloud 專案一分鐘的查詢費用。
每項專案每位使用者每分鐘：這是 Cloud 專案一分鐘內，任何特定使用者可使用的查詢費用。
下表詳細列出這些配額：
| 用量限制類型 | 查詢費用 |
|---|---|
| 每項專案每分鐘 | 1,200,000 |
| 每位使用者每項專案每分鐘 | 6,000 |
Gmail MCP 工具組配額
下表詳細列出各 gmailmcp.googleapis.com 工具組的查詢費用：
| 端點 | 工具 | 查詢費用 |
|---|---|---|
/mcp/v1 |
|
10 |
|
40 |
|
|
10 |
|
|
10 |
|
|
5 |
|
|
1 |
|
|
10 |
|
|
10 |
|
|
10 |
詳情請參閱 Gmail MCP API 參考資料。