La API de Gmail está sujeta a límites de uso que restringen la frecuencia con la que se pueden llamar a los métodos de la API. Los límites se definen en términos de unidades de cuota, una unidad de medida abstracta que representa el uso de recursos de Gmail.
Cuotas de la API de Gmail
Se aplican dos tipos de cuotas:
Por minuto y por proyecto: Es la cantidad de unidades de cuota que tu proyecto de Google Cloud puede usar en un minuto.
Por minuto, por usuario y por proyecto: Es la cantidad de unidades de cuota que puede usar cualquier usuario en particular en tu proyecto de Cloud. Este límite tiene como objetivo ayudarte a garantizar una distribución justa del uso entre tus usuarios.
En la siguiente tabla, se detallan estos límites:
| Tipo de límite de uso | Límite |
|---|---|
| Por minuto, por proyecto | 1,200,000 unidades de cuota |
| Por minuto, por usuario y por proyecto | 6,000 unidades de cuota |
Para obtener información sobre cómo manejar los errores de límite, consulta Cómo resolver errores.
Límite de facturación diario
Este límite por día y por proyecto define la cantidad máxima de unidades de cuota que tu proyecto de Google Cloud puede usar en un período de 24 horas antes de que se apliquen cargos.
El uso por debajo de este umbral no genera cargos adicionales y no se factura tu cuenta de Google Cloud. Los detalles de facturación completos se compartirán más adelante en 2026, con un aviso de al menos 90 días antes de que entren en vigencia los cambios.
No puedes solicitar un aumento en este límite de umbral diario.
En la siguiente tabla, se detalla el límite:
| Tipo de límite de umbral | Límite |
|---|---|
| Por día y por proyecto | 80,000,000 unidades de cuota |
Para obtener más información, consulta Modelo estandarizado de Google Workspace para herramientas y APIs de agentes.
Uso de la cuota por método
La cantidad de unidades de cuota consumidas por solicitud varía según el método invocado. En la siguiente tabla, se describe el uso de unidades de cuota por método:
| Método | Unidades de cuota |
|---|---|
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 |
Cuando se usa la API de Gmail, también hay un límite de 500 destinatarios por mensaje de correo electrónico.
Cómo resolver errores de cuota basados en el tiempo
Para todos los errores basados en el tiempo (un máximo de N solicitudes por X minutos), te recomendamos que tu código detecte la excepción y use una retirada exponencial truncada para asegurarte de que tus dispositivos no generen una carga excesiva.
La retirada exponencial es una estrategia estándar de manejo de errores para aplicaciones de red. Un algoritmo de retirada exponencial reintenta las solicitudes con tiempos de espera que aumentan de forma exponencial entre las solicitudes, hasta un tiempo de retirada máximo. Si las solicitudes siguen sin tener éxito, es importante que los retrasos entre las solicitudes aumenten con el tiempo hasta que la solicitud se realice correctamente.
Algoritmo de ejemplo
Un algoritmo de retirada exponencial vuelve a intentar las solicitudes de forma exponencial, lo que aumenta el tiempo de espera entre los reintentos hasta un tiempo de retirada máximo. Por ejemplo:
- Realiza una solicitud a la API de Gmail.
- Si la solicitud falla, espera 1 +
random_number_millisecondssegundos y vuelve a intentarla. - Si la solicitud falla, espera 2 +
random_number_millisecondssegundos y vuelve a intentar la solicitud. - Si la solicitud falla, espera 4 +
random_number_millisecondssegundos y vuelve a intentarla. - Y así sucesivamente, hasta un tiempo de
maximum_backoff. - Continúa con la espera y los reintentos hasta llegar a una cantidad máxima, pero no aumentes el período de espera entre los reintentos.
Donde:
- El tiempo de espera es
min(((2^n)+random_number_milliseconds), maximum_backoff), connincrementado en 1 para cada iteración (solicitud). random_number_millisecondses un número aleatorio de milisegundos menor o igual que 1,000. Esto ayuda a evitar los casos en los que muchos clientes se sincronizan por alguna situación y todos realizan el reintento a la vez, lo que hace que se envíen solicitudes en oleadas sincronizadas. El valor derandom_number_millisecondsse vuelve a calcular después de cada reintento de solicitud.maximum_backoffsuele ser de 32 o 64 segundos. El valor apropiado depende del caso de uso.
El cliente puede seguir reintentando después de que alcanza el tiempo maximum_backoff.
Después de este punto, los reintentos no necesitan continuar con el aumento del tiempo de retirada. Por ejemplo, si un cliente usa un tiempo de maximum_backoff de 64 segundos, luego de alcanzar este valor, el cliente puede volver a intentarlo cada 64 segundos. En algún momento, se debe evitar que los clientes vuelvan a intentarlo de forma ilimitada.
El tiempo de espera entre los reintentos y la cantidad de reintentos dependen del caso práctico y las condiciones de la red.
Precios
Todo uso estándar de la API de Gmail está disponible sin costo adicional. Se prevé que, más adelante en 2026, superar los límites de solicitudes de cuota generará cargos en tu cuenta de facturación de Google Cloud. Para obtener más información, consulta Modelo estandarizado de Google Workspace para herramientas y APIs de agentes.
Solicita un aumento de la cuota
Según el uso de recursos de tu proyecto, es posible que desees solicitar un ajuste de cuota. Las llamadas a la API realizadas por una cuenta de servicio se consideran como si se usara una sola cuenta. Solicitar una cuota ajustada no garantiza la aprobación. Las solicitudes de ajuste de cuota que aumentarían significativamente el valor de la cuota pueden tardar más en aprobarse.
No todos los proyectos tienen las mismas cuotas. A medida que tu uso de Google Cloud aumenta con el tiempo, es posible que debas incrementar los valores de tus cuotas. Si prevés un aumento considerable en el uso, puedes solicitar ajustes en la cuota de forma proactiva en la página Cuotas y límites del sistema de la consola de Google Cloud.
Para obtener más información, consulta los siguientes recursos:
- Acerca de los ajustes de cuota
- Cómo ver el uso y los límites de tu cuota
- Solicita un límite de cuota más alto
Cuotas del servidor de MCP de Gmail
El servidor de MCP de Gmail usa una métrica de asignación de costos de consultas. En las siguientes tablas, se detalla el costo de la consulta para cada método del servidor de MCP de Gmail por sección:
Cuotas de MCP de Gmail
Se aplican dos tipos de cuotas:
Por minuto y por proyecto: Este es el costo de la consulta para tu proyecto de Google Cloud por un minuto.
Por minuto, por usuario y por proyecto: Este es el costo de la consulta para tu proyecto de Google Cloud durante un minuto que puede usar cualquier usuario en particular.
En la siguiente tabla, se detallan estas cuotas:
| Tipo de límite de uso | Costo de la búsqueda |
|---|---|
| Por minuto, por proyecto | 1,200,000 |
| Por minuto, por usuario y por proyecto | 6,000 |
Cuotas del conjunto de herramientas de MCP de Gmail
En la siguiente tabla, se detalla el costo de la consulta para cada conjunto de herramientas de gmailmcp.googleapis.com:
| Extremo | Herramienta | Costo de la búsqueda |
|---|---|---|
/mcp/v1 |
|
10 |
|
40 |
|
|
10 |
|
|
10 |
|
|
5 |
|
|
1 |
|
|
10 |
|
|
10 |
|
|
10 |
Para obtener más información, consulta la referencia de la API de MCP de Gmail.
Temas relacionados
- Solicitudes en lotes
- Sugerencias sobre el rendimiento
- Límites para enviar y recibir correos electrónicos
- Límites de envío de Gmail en Google Workspace