Gmail API phải tuân theo các giới hạn sử dụng, hạn chế tần suất bạn có thể gọi các phương thức API. Hạn mức được xác định theo đơn vị hạn mức, một đơn vị đo lường trừu tượng thể hiện mức sử dụng tài nguyên của Gmail.
Hạn mức API Gmail
API Gmail thực thi hai loại hạn mức:
Mỗi phút cho mỗi dự án: Đây là số đơn vị hạn mức mà dự án Google Cloud của bạn có thể sử dụng trong một phút.
Mỗi phút trên mỗi người dùng trên mỗi dự án: Đây là số đơn vị hạn mức mà một người dùng cụ thể có thể sử dụng trong dự án trên đám mây của bạn. Hạn mức này giúp đảm bảo việc phân bổ mức sử dụng một cách công bằng cho người dùng.
Bảng sau đây trình bày chi tiết về các giới hạn này:
| Loại hạn mức sử dụng | Hạn mức |
|---|---|
| Mỗi phút mỗi dự án | 1.200.000 đơn vị hạn mức |
| Mỗi phút trên mỗi người dùng trên mỗi dự án | 6.000 đơn vị hạn mức |
Để biết thông tin về cách xử lý lỗi giới hạn, hãy xem bài viết Giải quyết lỗi.
Ngưỡng thanh toán hằng ngày
Giới hạn mỗi ngày cho mỗi dự án này xác định số lượng đơn vị hạn mức tối đa mà dự án trên đám mây của bạn có thể sử dụng trong khoảng thời gian 24 giờ trước khi bị tính phí.
Mức sử dụng dưới ngưỡng này sẽ không phát sinh thêm phí và tài khoản Google Cloud của bạn sẽ không bị tính phí. Google sẽ chia sẻ thông tin chi tiết đầy đủ về việc thanh toán vào cuối năm 2026 và thông báo trước ít nhất 90 ngày trước khi có bất kỳ thay đổi nào có hiệu lực.
Bạn không thể yêu cầu tăng ngưỡng giới hạn hằng ngày này.
Bảng sau đây trình bày chi tiết về hạn mức:
| Loại ngưỡng giới hạn | Hạn mức |
|---|---|
| Mỗi ngày mỗi dự án | 80.000.000 đơn vị hạn mức |
Để biết thêm thông tin, hãy xem bài viết Mô hình chuẩn hoá của Google Workspace cho các công cụ và API của tác nhân.
Mức sử dụng hạn mức theo phương thức
Số đơn vị hạn mức mà mỗi yêu cầu sử dụng sẽ khác nhau tuỳ thuộc vào phương thức bạn gọi và tham số truy vấn. Bảng sau đây trình bày mức sử dụng đơn vị hạn mức theo từng phương thức:
| Phương thức | Các đơn vị hạn ngạch |
|---|---|
drafts.create |
10 |
drafts.delete |
10 |
drafts.get |
20 (60 khi format là full, raw hoặc 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 khi format là full, raw hoặc 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 khi format là full) |
threads.list |
10 |
threads.modify |
10 |
threads.trash |
20 |
threads.untrash |
10 |
watch |
100 |
Khi sử dụng API Gmail, bạn cũng chỉ có thể gửi cho tối đa 500 người nhận mỗi nội dung email.
Giải quyết lỗi hạn mức theo thời gian
Đối với tất cả lỗi dựa trên thời gian (tối đa N yêu cầu mỗi X phút), bạn nên để mã của mình phát hiện ngoại lệ và sử dụng thuật toán thời gian đợi luỹ thừa bị cắt bớt để đảm bảo thiết bị của bạn không tạo ra tải quá mức.
Thuật toán thời gian đợi luỹ thừa là một chiến lược xử lý sai số chuẩn cho các ứng dụng mạng. Thuật toán thời gian đợi luỹ thừa sẽ thử lại các yêu cầu bằng cách tăng thời gian chờ theo cấp luỹ thừa giữa các yêu cầu, cho đến thời gian đợi tối đa. Nếu các yêu cầu vẫn không thành công, thì điều quan trọng là độ trễ giữa các yêu cầu phải tăng dần theo thời gian cho đến khi yêu cầu thành công.
Thuật toán mẫu
Thuật toán thời gian đợi luỹ thừa sẽ thử lại các yêu cầu theo cấp luỹ thừa, tăng thời gian chờ giữa các lần thử lại cho đến thời gian đợi tối đa. Ví dụ:
- Tạo yêu cầu đến API Gmail.
- Nếu yêu cầu không thành công, hãy đợi 1 +
random_number_millisecondsrồi thử lại yêu cầu. - Nếu yêu cầu không thành công, hãy đợi 2 +
random_number_millisecondsrồi thử lại yêu cầu. - Nếu yêu cầu không thành công, hãy đợi 4 +
random_number_millisecondsrồi thử lại yêu cầu. - Và cứ thế, tối đa
maximum_backofflần. - Tiếp tục chờ và thử lại cho đến khi đạt số lần thử lại tối đa, nhưng không tăng khoảng thời gian chờ giữa các lần thử lại.
trong đó:
- Thời gian chờ là
min(((2^n)+random_number_milliseconds), maximum_backoff), vớintăng thêm 1 cho mỗi lần lặp (yêu cầu). random_number_millisecondslà một số mili giây ngẫu nhiên nhỏ hơn hoặc bằng 1.000. Điều này giúp tránh trường hợp nhiều ứng dụng khách được đồng bộ hoá theo một số tình huống và tất cả đều thử lại cùng một lúc, gửi yêu cầu theo các đợt đồng bộ hoá. Giá trị củarandom_number_millisecondsđược tính toán lại sau mỗi yêu cầu thử lại.maximum_backoffthường là 32 hoặc 64 giây. Giá trị thích hợp phụ thuộc vào trường hợp sử dụng.
Ứng dụng có thể tiếp tục thử lại sau khi đạt đến thời gian maximum_backoff.
Các lần thử lại sau thời điểm này không cần tiếp tục tăng thời gian đợi. Ví dụ: nếu một ứng dụng khách sử dụng thời gian maximum_backoff là 64 giây, thì sau khi đạt đến giá trị này, ứng dụng khách có thể thử lại sau mỗi 64 giây. Tại một thời điểm nào đó, bạn nên ngăn ứng dụng thử lại vô thời hạn.
Thời gian chờ giữa các lần thử lại và số lần thử lại phụ thuộc vào trường hợp sử dụng và điều kiện mạng của bạn.
Giá
Mọi hoạt động sử dụng tiêu chuẩn của API Gmail đều được cung cấp mà không mất thêm phí. Nếu vượt quá hạn mức yêu cầu, bạn sẽ phải trả phí cho tài khoản thanh toán trên Google Cloud vào cuối năm 2026. Để biết thêm thông tin, hãy xem bài viết Mô hình chuẩn hoá của Google Workspace cho các công cụ và API của tác nhân.
Yêu cầu tăng hạn mức
Tuỳ thuộc vào mức sử dụng tài nguyên của dự án, bạn có thể cần yêu cầu điều chỉnh hạn mức. Các lệnh gọi API của một tài khoản dịch vụ được coi là sử dụng một tài khoản duy nhất. Việc đăng ký hạn mức điều chỉnh không đảm bảo rằng bạn sẽ được phê duyệt. Những yêu cầu điều chỉnh hạn mức có thể làm tăng đáng kể giá trị hạn mức sẽ mất nhiều thời gian hơn để được phê duyệt.
Không phải dự án nào cũng có hạn mức giống nhau. Khi bạn sử dụng Google Cloud ngày càng nhiều theo thời gian, có thể bạn sẽ cần tăng giá trị hạn mức. Nếu dự kiến mức sử dụng sẽ tăng đáng kể trong thời gian tới, bạn có thể chủ động yêu cầu điều chỉnh hạn mức trên trang Hạn mức và giới hạn hệ thống trong Google Cloud Console.
Để tìm hiểu thêm, hãy xem các tài nguyên sau:
Hạn mức máy chủ MCP cho Gmail
Máy chủ MCP cho Gmail sử dụng chỉ số phân bổ chi phí truy vấn. Các bảng sau đây trình bày chi tiết chi phí truy vấn cho từng phương thức máy chủ MCP của Gmail theo phần:
Hạn mức MCP cho Gmail
Máy chủ thực thi hai loại hạn mức:
Mỗi phút cho mỗi dự án: Đây là chi phí truy vấn cho dự án trên đám mây của bạn trong một phút.
Mỗi phút cho mỗi người dùng trên mỗi dự án: Đây là chi phí truy vấn cho dự án trên đám mây của bạn trong một phút mà bất kỳ người dùng cụ thể nào cũng có thể sử dụng.
Bảng sau đây trình bày chi tiết về các hạn mức này:
| Loại hạn mức sử dụng | Chi phí truy vấn |
|---|---|
| Mỗi phút mỗi dự án | 1.200.000 |
| Mỗi phút trên mỗi người dùng trên mỗi dự án | 6.000 |
Hạn mức của bộ công cụ MCP cho Gmail
Bảng sau đây trình bày chi tiết chi phí truy vấn cho từng gmailmcp.googleapis.com
bộ công cụ:
| Điểm cuối | Công cụ | Chi phí truy vấn |
|---|---|---|
/mcp/v1 |
|
10 |
|
40 |
|
|
10 |
|
|
10 |
|
|
5 |
|
|
1 |
|
|
10 |
|
|
10 |
|
|
10 |
Để biết thêm thông tin, hãy xem Tài liệu tham khảo API MCP của Gmail.