מגבלות שימוש

השימוש ב-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 של סוכנים.

ניצול המכסה לכל שיטה

מספר יחידות המכסה שכל בקשה צורכת משתנה בהתאם ל-method שאתם קוראים לו ולפרמטרים של השאילתה. בטבלה הבאה מפורט השימוש ביחידות המכסה לכל שיטה:

שיטה יחידות מיכסה
drafts.create 10
drafts.delete 10
drafts.get ‫20 (60 כש-format הוא full, raw או html)
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 (60 כש-format הוא full, raw או html)
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 (120 כש-format הוא full)
threads.list 10
threads.modify 10
threads.trash 20
threads.untrash 10
watch 100

כשמשתמשים ב-Gmail API, יש גם מגבלה של 500 נמענים לכל הודעת אימייל.

פתרון שגיאות במכסות מבוססות-זמן

בכל השגיאות שקשורות לזמן (מקסימום N בקשות לכל X דקות), מומלץ שהקוד יתפוס את החריגה וישתמש בהשהיה מעריכית קטועה לפני ניסיון חוזר (truncated exponential backoff) כדי לוודא שהמכשירים לא יוצרים עומס מוגזם.

השהיה מעריכית לפני ניסיון חוזר (exponential backoff) היא אסטרטגיה סטנדרטית לטיפול בשגיאות באפליקציות רשת. אלגוריתם של השהיה מעריכית לפני ניסיון חוזר (exponential backoff) מבצע ניסיון חוזר של בקשות באמצעות הגדלה אקספוננציאלית של זמני ההמתנה בין הבקשות, עד למשך ההשהיה המקסימלי. אם הבקשות עדיין נכשלות, חשוב להגדיל את ההשהיות בין הבקשות לאורך זמן עד שהבקשה תצליח.

אלגוריתם לדוגמה

אלגוריתם של השהיה מעריכית לפני ניסיון חוזר (exponential backoff) מבצע ניסיון חוזר של בקשות באופן מעריכי, ומגדיל את זמן ההמתנה בין הניסיונות החוזרים עד למשך ההשהיה המקסימלי. לדוגמה:

  1. שולחים בקשה ל-Gmail API.
  2. אם הבקשה נכשלת, צריך להמתין ‎1 + random_number_milliseconds‎ שניות, ולאחר מכן לנסות שוב את הבקשה.
  3. אם הבקשה נכשלת, צריך להמתין ‎2 + random_number_milliseconds‎ שניות, ולאחר מכן לנסות שוב את הבקשה.
  4. אם הבקשה נכשלת, צריך להמתין ‎4 + random_number_milliseconds‎ שניות, ולאחר מכן לנסות שוב את הבקשה.
  5. וכן הלאה, עד לפעם ה-maximum_backoff.
  6. ממשיכים להמתין ולנסות שוב עד למספר המקסימלי של ניסיונות חוזרים, אבל לא מגדילים את תקופת ההמתנה בין הניסיונות החוזרים.

כאשר:

  • זמן ההמתנה הוא 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 יגדל עם הזמן, יכול להיות שתצטרכו להגדיל את ערכי המכסות. אם אתם צופים עלייה משמעותית בשימוש, אתם יכולים לבקש שינויים במכסות באופן יזום בדף Quotas & System Limits במסוף Google Cloud.

למידע נוסף, אפשר לעיין במקורות המידע הבאים:

מכסות בשרת ה-MCP של Gmail

שרת ה-MCP של Gmail משתמש במדד הקצאת עלות לשאילתה. בטבלאות הבאות מפורטת עלות השאילתה לכל שיטה של שרת Gmail MCP לפי קטע:

מכסות MCP ב-Gmail

השרת אוכף שני סוגים של מכסות:

  • לדקה לפרויקט בענן: עלות השאילתה לפרויקט בענן לדקה.

  • לדקה למשתמש לפרויקט: עלות השאילתה לפרויקט בענן לדקה, שמשתמש ספציפי יכול להשתמש בה.

בטבלה הבאה מפורטות המכסות האלה:

סוג מכסת השימוש עלות השאילתה
לדקה לכל פרויקט 1,200,000
לדקה לכל משתמש בכל פרויקט 6,000

מכסות לערכת הכלים של MCP ב-Gmail

בטבלה הבאה מפורטת עלות השאילתה לכל ערכת כלים של gmailmcp.googleapis.com:

נקודת קצה כלי עלות השאילתה

‎/mcp/v1

create_draft

10

get_thread

40

label_message

10

label_thread

10

list_drafts

5

list_labels

1

search_threads

10

unlabel_message

10

unlabel_thread

10

מידע נוסף זמין במאמרי העזרה של Gmail MCP API.