LinkedIn
Instagram
WhatsApp
Telegrama
Gmail
Outlook
Calendario de Google
Únase a la comunidad SlackAPI de Gmail Notificaciones push: Guía Completa de Pub/Sub, Watch & History (2026)
Configurar notificaciones push de la API de Gmail de extremo a extremo: crear un tema de Pub/Sub, registrar un punto final de watch, decodificar cargas útiles de webhook, conciliar cambios con usuarios.historial.listar, automatizar la renovación de relojes y omitir la configuración completa de GCP con una alternativa de webhook unificado.
// 1. Registrar Gmail watch vía Unipile
const res = await fetch('https://api8.unipile.com:13815/api/v1'
+ '/cuentas/{id}/ver', {
method: POST,
headers: {
'X-API-KEY': 'TU_CLAVE_API',
'Content-Type': aplicación/json
},
body: JSON.stringify({
webhook_url: 'https://app.you.com/webhooks/gmail'
})
});
// 2. Recibir carga útil unificada del webhook
aplicación.Correo electrónico:('/webhooks/gmail', (req, res) => {
const { evento, id_cuenta, correo_electronico } = req.body;
evento: "nuevo_correo_electrónico" | historyId abstraído
gestionarNuevoCorreo(correo electrónico);
});Notificaciones push de la API de Gmail
Antes de implementar las notificaciones push de la API de Gmail en producción, es útil comprender exactamente qué son, en qué se diferencian del sondeo simple y qué infraestructura requieren.
Las notificaciones push de la API de Gmail son un mecanismo de entrega en tiempo real que utiliza Google Cloud Pub/Sub para enviar eventos de cambio del buzón a un punto final HTTPS controlado por el desarrollador. Cuando llega un nuevo mensaje o se modifica uno existente, Gmail publica una notificación que contiene un codificado historialId a un tema de Pub/Sub que posees, el cual luego reenvía ese evento a tu webhook. Tu servidor llama usuarios.historial.listar para recuperar los cambios reales.
Las notificaciones push de la API de Gmail eliminan la necesidad de realizar llamadas repetidas mensajes.lista en un horario. Los eventos se entregan a los pocos segundos del cambio del buzón, lo que reduce tanto la latencia como el uso de la cuota de API.
El canal de entrega es Google Cloud Pub/Sub, no una devolución de llamada HTTP directa de Gmail. Esto añade durabilidad: si tu punto final no está disponible temporalmente, Pub/Sub puede reintentar la entrega según su plazo de confirmación de suscripción.
Un endpoint de notificación de la API de Gmail expira después de 7 días. Su aplicación debe renovarlo de forma proactiva con un trabajo cron diario o arriesgarse a perder eventos de forma silenciosa. Este es un detalle operativo crítico cubierto en la sección Renovación.
Las notificaciones push de la API de Gmail entregan eventos en 1-10 segundos después del cambio. No tener que consultar constantemente significa un menor consumo de cuota en la API de Gmail y un tiempo de respuesta más rápido para tu aplicación. Ideal para cualquier caso de uso en tiempo real a nivel de bandeja de entrada: sincronización CRM, sistemas de ticketing, automatización de flujos de trabajo.
Sondeo mensajes.lista cada 60 segundos es más simple de configurar, pero introduce latencia artificial, desperdicia cuota en respuestas vacías y escala mal en un gran número de cuentas de usuario autenticadas. Aceptable solo para prototipos de bajo volumen.
Arquitectura: watch + Pub/Sub + historyId en un flujo
Las notificaciones push de la API de Gmail implican cuatro capas distintas que trabajan en secuencia. Comprender cada capa antes de escribir código evita los errores de implementación más comunes.
Tú envías a https://gmail.googleapis.com/gmail/v1/users/me/watch con el nombre de tu tema de Pub/Sub y, opcionalmente, un filtro de etiquetas. Gmail devuelve un historialId y un Vencimiento Marca de tiempo Unix. Guarda ambos. Este reloj expira en 7 días.
Cuando ocurre cualquier cambio en el buzón observado (mensaje nuevo, cambio de etiqueta, cambio de estado a leído/no leído), Gmail publica una notificación JSON en tu tema de Cloud Pub/Sub. La carga útil es un objeto codificado en base64 que contiene la dirección de correo electrónico del usuario y un nuevo historialId.
Tu suscripción de Pub/Sub reenvía el mensaje a un punto final push HTTPS registrado. Esta es la URL de tu webhook, la cual debe responder con HTTP 200-299 dentro del plazo de confirmación (predeterminado de 10 a 600 segundos). Una respuesta que no sea 2xx desencadena reintentos automáticos.
Decodifica los datos del mensaje Pub/Sub base64. Extrae el nuevo historialId. Compáralo con el últimoIdHistorial almacenada en tu base de datos para este usuario.
Llamar usuarios.historial.listar con inicioIdHistorial establecer a su valor almacenado. Gmail devuelve todos los cambios (mensajes nuevos, adiciones de etiquetas, eliminaciones) entre las dos ID. Actualice su últimoIdHistorial al nuevo valor. Nunca uses el historyId de la notificación de Pub/Sub como inicioIdHistorial directamente.
Programar una tarea cron diaria para llamar usuarios.ver nuevamente para cada cuenta de usuario autenticada. La renovación de la vigilancia es idempotente: una nueva llamada reemplaza el vencimiento anterior. Lo devuelto historialId se convierte en su nueva línea de base.
Un entero monotónicamente creciente asignado por Gmail a cada cambio de buzón. Es tu cursor para la sincronización incremental. Siempre guarda el último historyId por usuario en tu base de datos.
El punto final de la API de Gmail que registra una suscripción de notificación push para un buzón de correo. Devuelve una base de `historyId` y una marca de tiempo de Unix en milisegundos para la expiración. Debe renovarse dentro de los 7 días.
El endpoint de reconciliación. Dado un startHistoryId, devuelve todas las adiciones, eliminaciones y cambios de etiquetas de mensajes que ocurrieron después de ese punto. Aquí es donde obtienes los datos reales de los mensajes.
Requisitos previos: proyecto de GCP, tema de Pub/Sub, concesión de IAM
Las notificaciones push de la API de Gmail requieren tres recursos del lado de GCP antes de tu primera usuarios.ver llamada. La mayoría de los fallos de implementación se remontan a una concesión de IAM faltante en el tema de Pub/Sub, el paso que los desarrolladores omiten con mayor frecuencia.
En la consola de Google Cloud, crea o selecciona un proyecto existente. Navega a APIs y Servicios > Biblioteca y habilita el API de Gmail. También necesitas el API de Cloud Pub/Sub habilitado en el mismo proyecto. Asegúrate de que tus credenciales de cliente OAuth 2.0 incluyan https://www.googleapis.com/auth/gmail.readonly alcance (o un alcance más amplio si necesitas acceso de escritura). Para aplicaciones multiusuario, consulta nuestra guía sobre Integración OAuth 2.0 de Gmail y el Verificación de la aplicación de Google OAuth requisitos.
En la consola de GCP, en Pub/Sub > Temas, haga clic Crear tema. Ponle un nombre como notificaciones de gmail. El nombre completo del tema será projects/YOUR_PROJECT_ID/topics/gmail-notificaciones. Deberás pasar esta cadena exacta a usuarios.ver en el nombre del tema campo.
Este es el paso que la mayoría de los desarrolladores echan de menos. Gmail utiliza una cuenta de servicio gestionada por Google (gmail-api-push@system.gserviceaccount.com) para publicar notificaciones en tu tema de Pub/Sub. Sin otorgarle a esta cuenta Publicador de Pub/Sub papel en tu tema, usuarios.ver tendrá éxito pero nunca se entregarán notificaciones. En la Consola: Temas > seleccionar tu tema > Permisos > Añadir principal > introducir gmail-api-push@system.gserviceaccount.com > asignar rol Publicador de Pub/Sub.
Debajo de tu tema de Pub/Sub, crea un Suscripción push. Configure el extremo de push en la URL de su webhook HTTPS (debe usar un certificado TLS válido, se rechazarán los certificados autofirmados). Opcionalmente, configure un encabezado de validación de token para que su extremo pueda verificar que las solicitudes provienen de Google. Anote el nombre de la suscripción; es posible que lo necesite para monitorear las métricas de entrega en Cloud Monitoring.
Límite de 100 usuarios en aplicaciones no verificadas: Si tu pantalla de consentimiento de OAuth se encuentra en estado "En prueba", solo 100 cuentas de Gmail podrán autorizar tu aplicación. Este límite se aplica a todo Ámbitos de OAuth, incluido el punto final de observación. Para implementaciones de producción con más de 100 usuarios, debe completar el proceso de verificación de Google. Consulte nuestra guía completa sobre Límite de 100 usuarios y ruta de verificación.
Sin tema Pub/Sub. Sin concesión IAM. Sin cron de renovación de vigilancia de 7 días. Crea notificaciones push de Gmail con una URL de webhook.
Paso a paso: crear tema, suscripción y users.watch
Con los prerrequisitos de GCP en su lugar, aquí está el código completo para registrar un endpoint de watch de la API de Gmail tanto en Node.js como en Python, utilizando la biblioteca cliente de la API de Google.
const { google } = require('googleapis');
// Asume que el cliente OAuth2 ya está autorizado con un token de acceso válido
// Ver: https://www.unipile.com/gmail-oauth-20-integration-complete-guide/
async function RegistrarGmailVigilar(autenticación, userId = yo) {
const gmail = Google.gmail({ version: 'v1'auth });
const response = await gmail.usuarios.reloj({
ID de usuario,
cuerpoDeLaSolicitud: {
// El nombre completo de tu tema de Pub/Sub
NombreDelTema: 'proyectos/TU_PROJECT_ID/temas/gmail-notifications',
// Opcional: filtrar solo por etiquetas específicas
IDs de etiquetas: ['BANDEJA DE ENTRADA'],
labelFilterBehavior: 'INCLUIR'
}
});
const { historialId, expiracion } = respuesta.data;
// Guarde esto por usuario en su base de datos
await base de datos.insertar o actualizar({
ID de usuario,
lastHistoryId: historyId,
// la expiración es una marca de tiempo Unix en milisegundos
watchExpiry: new Fecha(parseIntcaducidad
});
consola.log(`Observación registrada. historyId: ${historyId}, caduca: ${expiration}`);
return respuesta.datos;
}from googleapiclient.discovery import construir
from google.oauth2.credenciales import Credenciales
def registrar_gmail_vercredenciales: Credenciales, id_de_usuario: cadena = yo) -> dict:
"Registrar notificaciones push de la API de Gmail para un usuario autenticado."
servicio = construir('Gmail', 'v1', credentials=credentials)
cuerpo = {
'nombreDelTema': 'proyectos/TU_PROJECT_ID/temas/gmail-notifications',
'idsDeEtiquetas': ['BANDEJA DE ENTRADA'],
'comportamientoFiltroEtiqueta': 'INCLUIR'
}
resultado = servicio.usuarios().reloj(userId=user_id, cuerpo=body).ejecutar()
#: Almacena los datos por usuario en tu base de datos
db_upsert(id_usuario=id_usuario,
último_id_historial=resultado['idHistorial'],
vencimiento_reloj=entero(resultado['caducidad']) // 1000)
return resultadoManejo de la carga útil del webhook de notificación push de la API de Gmail
Cuando Gmail envía una notificación push, tu punto final HTTPS recibe un mensaje push de Pub/Sub. Los datos reales de cambio de Gmail están doblemente codificados: el sobre de Pub/Sub contiene una cadena JSON codificada en base64 que a su vez contiene el correo electrónico del usuario y el historyId.
aplicación.Correo electrónico:('/webhooks/gmail', async (req, res) => {
Acusar de inmediato: Pub/Sub reintenta en no-2xx
res.estado(200).fin();
intentar {
const mensaje = req.body.mensaje;
si (!mensaje?.datos) regresar;
// Decodificar el campo de datos de Pub/Sub en base64
const descifrado =
Tampón.from(mensaje.datos, base64).toString('utf-8');
const carga útil = JSON.analizar(decodificado);
payload = { emailAddress: "usuario@gmail.com", historyId: "12345" }
const { emailAddress, historyId } = payload;
// Reconciliación de cola (no bloquear el ack)
await cola.encolar({ emailAddress, historyId });
} catch (err) {
// Registrar pero no volver a lanzar: ack ya fue enviado
consola.error('Error de análisis de Webhook', err);
}
});import base64, json
from frasco import Flask, request, jsonify
apartamento = Matraz(__nombre__)
@app.ruta('/webhooks/gmail', métodos=[POST])
def webhook de gmail():
#: Confirmar inmediatamente
datos = solicitud.get_json(silencioso=True) o {}
mensaje = datos.consiga('mensaje', {})
si 'datos' en mensaje:
#: Descifrar Base64 y analizar JSON
crudo = base64.b64decode(mensaje['datos'] + '==')
carga útil = json.cargascrudo
# { "emailAddress": "user@gmail.com", "historyId": "12345" }
el correo electrónico = carga útil.consiga('dirección de correo electrónico')
id_historial = carga.consiga('idHistorial')
#: Puesta en cola de la conciliación asíncrona
enviar_a_cola_reconciliar(correo electrónico, historial_id)
return convertir a JSON({}), 200Conciliar cambios con users.history.list
La notificación de Pub/Sub solo te dice algo cambió. No te dice qué. Debes llamar usuarios.historial.listar con tu guardado últimoIdHistorial como el cursor para obtener el delta real.
async function reconciliarHistorial(auth, direccíon de correo electrónico, nuevo ID de historial) {
const gmail = Google.gmail({ version: 'v1'auth });
// Recupera nuestro lastHistoryId almacenado para este usuario
const usuario = await base de datos.encontrarPorEmail(direcciónDeCorreoElectrónico);
const startHistoryId = user.ultimoIdHistorial;
intentar {
const response = await historial.usuarios.gmail.list({
userId: yo,
// Utiliza el ID ALMACENADO como cursor: NO el historial de notificaciones nuevoId
idInicioHistorial,
// Filtrar solo adiciones de mensajes (opcional)
historyTypes: ['mensajeAñadido']
});
const historias = response.data.historial || [];
para (const (registro de historias) {
para (const added of (record.messagesAdded || [])) {
// agregado.mensaje = { id, threadId, labelIds }
await procesarNuevoMensaje(autenticación, added.message.id);
}
}
Actualiza el cursor al nuevo historyId de la notificación
await base de datos.actualizarÚltimoIdHistorial(direcciónDeCorreoElectrónico, nuevoIdDeHistorial);
} catch (err) {
si (err.code === 404) {
// El historyId es demasiado antiguo (> 7 días). Reinicializar desde messages.list
await reinicializarDesdeMensajes(autenticación, direcciónDeCorreoElectrónico);
} de lo contrario {
lanzar error;
}
}
}El historyId en la notificación de Pub/Sub es el actual estado. Tu inicioIdHistorial debe ser el anterior valor que almacenó. Usar historyId de notificación directamente como startHistoryId significa que perderá todos los cambios entre su último punto procesado y ahora.
Pub/Sub podría entregar la misma notificación más de una vez. Su lógica de reconciliación debe ser idempotente: procesar el mismo ID de mensaje dos veces no debe tener ningún efecto. Use una restricción única en los ID de mensaje en su base de datos, o verifique la existencia antes de insertar.
Si pasas un startHistoryId anterior a 7 días, la API devuelve un 404. En este caso, recurre a mensajes.lista para resincronizar desde cero, luego llamar usuarios.ver de nuevo para obtener una línea base historyId actualizada.
Si ocurrieron muchos cambios entre tu historial historyId anterior y ahora, la respuesta de history.list puede estar paginada. Sigue siempre tokenPaginaSiguiente hasta agotar antes de actualizar tu cursor almacenado.
Estrategia de renovación de watch: el problema de la expiración de 7 días
Una notificación de Gmail API expira silenciosamente después de 7 días. No hay renovación automática ni notificación de advertencia. Si tu cron falla, llegan nuevos correos electrónicos pero tu aplicación no recibe nada, sin errores en ningún extremo. Esto hace que la renovación sea la parte más crítica a nivel operativo de cualquier implementación de notificaciones push de Gmail.
Renovar diariamente, no cada 7 días. Ejecuta tu cron de renovación cada 24 horas (no cada 6 o 7 días). La renovación de vigilancia es idempotente: llamar usuarios.ver vuelve a restablecer el temporizador de 7 días. Una cadencia diaria te da un margen de seguridad de 6 días contra fallos transitorios.
// Daily cron: 0 3 * * * (runs at 3am daily)
async function renewAllWatches() {
// Get all authenticated users from your database
const users = await db.getAllActiveUsers();
for (const user of users) {
try {
// Refresh the access token if needed
const auth = await getAuthClient(user.id);
const gmail = google.gmail({ version: 'v1', auth });
const res = await gmail.users.watch({
userId: 'me',
requestBody: {
topicName: 'projects/YOUR_PROJECT_ID/topics/gmail-notifications',
labelIds: ['INBOX']
}
});
// Update historyId baseline : new watch returns a fresh historyId
await db.update(user.id, {
lastHistoryId: res.data.historyId,
watchExpiry: new Date(parseInt(res.data.expiration))
});
} catch (err) {
if (err.code === 401) {
// Refresh token revoked : user needs to re-authorize
await db.markUserDisconnected(user.id);
} else if (err.code === 404) {
// Watch expired : call watch again (already doing this, so 404 = retry next run)
console.warn(`Watch already expired for ${user.email}, will retry`);
} else {
// Log and continue : don't abort the entire cron for one user
console.error(`Watch renewal failed for ${user.email}`, err);
}
}
}
}Unipile gestiona la renovación de Watch automáticamente en nombre de cada usuario autenticado. No se necesita ningún trabajo cron.
Resolución de problemas de notificaciones push de la API de Gmail
Estas son las cuatro clases de errores que representan casi todos los fallos en las notificaciones push de Gmail. La mayoría tiene una causa raíz única, una vez que sabes qué buscar.
| Error / Síntoma | Causa raiz | Arregla | Severidad |
|---|---|---|---|
| 403 en usuarios.watch | Cuenta de servicio de Gmail gmail-api-push@system.gserviceaccount.com no se le otorgó el rol de Publicador de Pub/Sub en el tema. |
En la Consola de GCP: Pub/Sub > Temas > tu tema > Permisos. Agrega la cuenta de servicio con el rol de Publicador de Pub/Sub. | Bloqueador |
| El reloj es exitoso pero no se reciben notificaciones | La URL del punto de conexión de inserción de la suscripción de Pub/Sub no está registrada, fue rechazada por Google (TLS no válida) o el tipo de suscripción de inserción es "Pull" en lugar de "Push". | Verifica que tu suscripción sea del tipo "Push" con tu URL de webhook como punto final. Asegúrate de que el certificado TLS sea válido (no autofirmado). El punto final de prueba devuelve 200. | Bloqueador |
| 404 en history.list: historyId demasiado antiguo | Tu almacenado últimoIdHistorial es mayor de 7 días. Gmail solo conserva el historial por 7 días. |
Retroceder a mensajes.lista para resincronizar. Luego llama usuarios.ver para una nueva base de datos historyId. |
Recuperable |
| Token de validación del punto final de inserción rechazado | Google envía una cabecera X-Goog-Channel-Token. Si tu endpoint la valida y el token no coincide, devuelve un código no 2xx y Pub/Sub reintenta indefinidamente. | Deshabilite la validación de tokens durante la configuración inicial o configure el mismo valor de token tanto en la configuración de suscripción de GCP como en la configuración de su aplicación. | Recuperable |
gmail-api-push@system.gserviceaccount.com no se concedió el publicador de Pub/Sub.Cuotas y límites de frecuencia para las notificaciones push de la API de Gmail
Las notificaciones push de la API de Gmail tienen restricciones de cuota específicas que difieren de los grupos de cuotas estándar de la API de Gmail. La restricción clave es el rendimiento de eventos por usuario.
Tasa máxima de notificación de Pub/Sub por usuario autenticado. Los picos pueden exceder temporalmente esta tasa, pero se controlan con el tiempo. Si un buzón recibe más de 1 cambio por segundo de forma continua, las notificaciones se agruparán o se retrasarán, no se descartarán.
Vencimiento máximo de la vigilancia. Todos los relojes deben ser renovados antes de esta fecha límite. Gmail retiene historial.lista datos para la misma ventana de 7 días: un historyId de más de 7 días devuelve un 404.
Cuota diaria predeterminada de la API de Gmail por proyecto. Cada usuarios.historial.listar la llamada cuesta 5 unidades. usuarios.ver cuesta 100 unidades por llamada. Planifique su volumen de conciliación en consecuencia.
Para un análisis más detallado de las cuotas por método, los límites por usuario y los procedimientos de solicitud de aumento de cuota, consulte nuestro dedicado Límites de frecuencia y cuotas de la API de Gmail.
Compensaciones: Pub/Sub vs. IMAP IDLE vs. sondeo vs. webhook unificado
Elegir la estrategia correcta de notificaciones push de Gmail depende de las limitaciones de tu infraestructura, las necesidades de cobertura del proveedor y la tolerancia operativa. Aquí hay una comparación directa de los cuatro enfoques.
| Acercamiento | Latencia | Complejidad de la configuración | Multiproveedor | Gastos generales de operaciones |
|---|---|---|---|---|
| Gmail Pub/Sub observar | 1-10s | Alto - GCP, IAM, cron | Solo Gmail | renovación de 7 días cron |
| IMAP IDLE | 1-30s | Mediano - TCP persistente | Servidores IMAP de Gmail | Gestión de conexión persistente |
| Sondeo | retraso de 30-300 s | Bajo | Cualquier proveedor | Quema de cuotas alta |
| Webhook unificado (Unipile) | 1-10s | Bajo - 1 URL de webhook | Gmail + Outlook + IMAP | Ninguno - administrado |
La Alternativa Unificada de Webhooks: Gmail + Outlook + IMAP con un solo endpoint
Si necesita notificaciones push de la API de Gmail más eventos en tiempo real de buzones de Outlook e IMAP - con un formato de carga útil unificado y sin infraestructura GCP - Unipile's API de Gmail resume toda la capa de Pub/Sub. Como intermediario técnico independiente, Unipile actúa en nombre de cada usuario autenticado para entregar eventos de correo electrónico a través de una única URL de webhook que su aplicación ya controla.
No hay tema de Pub/Sub que crear, ni concesión de IAM que configurar, ni proyecto de GCP que mantener. El registro y la renovación de watch ocurren dentro de la infraestructura de Unipile, no en la tuya.
La expiración de la vigilancia de 7 días se maneja en nombre de cada cuenta vinculada. Nunca se necesita un trabajo cron de renovación. Si se revoca un token de actualización, Unipile presenta un webhook de estado de cuenta en lugar de omitir eventos silenciosamente.
Recibes un objeto de correo electrónico analizado y normalizado, no un historial ID sin procesar. No es necesario llamar usuarios.historial.listar o administrar cursores por usuario. Unipile resuelve el delta y entrega datos de mensajes estructurados.
El mismo endpoint de webhook y el mismo esquema de eventos cubren Gmail, Outlook (incluyendo Microsoft 365 / Exchange Online) e IMAP. No hay lógica de integración por proveedor, ni webhooks separados para suscripciones de Microsoft Graph frente a notificaciones de publicación/suscripción de Gmail.
// 1. Vincular la cuenta de Gmail del usuario (OAuth en nombre del usuario autenticado)
// Ver: https://developer.unipile.com/docs/getting-started
// 2. Configura tu webhook una vez
const configuración = await fetch('https://api8.unipile.com:13815/api/v1/webhooks', {
method: POST,
cabeceras: {
'X-API-KEY': 'TU_CLAVE_API',
'Content-Type': aplicación/json
},
body: JSON.stringify({
url: 'https://app.you.com/webhooks/email',
eventos: ['correo.nuevo']
})
});
// 3. Manejar carga útil unificada: la misma forma para Gmail, Outlook, IMAP
aplicación.Correo electrónico:('/webhooks/email', (req, res) => {
const { evento, id_cuenta, correo_electronico } = req.body;
// evento: "email.nuevo"
// proveedor de correo electrónico: "gmail" | "outlook" | "imap"
// email.asunto, .de, .para, .cuerpo_html...
// Sin historyId. Sin base64. Sin cursor que administrar.
procesarCorreoEntrante(correo electrónico);
res.estado(200).fin();
});Unipile no crea un archivo de correo electrónico paralelo ni almacena el contenido de los mensajes de forma independiente. El acceso se limita a la sesión de cada usuario autenticado. Unipile recupera los datos del correo electrónico en nombre de cada cuenta vinculada y los entrega a su punto final de webhook en tiempo real. No se retiene ningún dato más allá de lo necesario para entregar la carga útil del webhook.
Unipile es un intermediario técnico independiente. Actúa en nombre de cada usuario autenticado que ha autorizado su aplicación a través de OAuth. Unipile no está afiliado, respaldado ni patrocinado por Google. Utiliza los mismos puntos finales de la API de Gmail descritos en esta guía, de forma individual para cada usuario, bajo la propia autorización OAuth de cada usuario. Las credenciales nunca se comparten entre cuentas. Todas las operaciones son una decisión del cliente delegada a la infraestructura de Unipile.
Unipile transmite los límites de la API de Gmail y las restricciones de cuota a su aplicación a través de su propia capa de administración de cuotas. Las decisiones sobre el volumen de eventos, la frecuencia de sondeo y el manejo de mensajes siguen siendo una decisión del cliente. Unipile expone los errores de cuota de la API de Gmail como eventos webhook estructurados para que su aplicación pueda responder de manera adecuada.
Conecta tu primera cuenta de Gmail en minutos. Sin proyecto GCP. Sin facturación de Pub/Sub. Sin crons de renovación de watch. Ver nuestro Guía de integración de la API de Gmail y el Resumen del proveedor de API de correo electrónico para explorar todos los proveedores admitidos.
Notificaciones Push de la API de Gmail - Preguntas Frecuentes
Respuestas a las preguntas más comunes sobre las notificaciones push de la API de Gmail, la configuración de Pub/Sub, historyId, la renovación de watch y las alternativas de sincronización de correo electrónico en tiempo real.
Notificaciones push de la API de Gmail Google Cloud Pub/Sub para enviar eventos de cambio de buzón en tiempo real a tu webhook HTTPS. Registras un endpoint de vigilancia a través de usuarios.ver, que vincula un buzón de Gmail a un tema de Pub/Sub de tu propiedad. Cuando ocurre un cambio —un mensaje nuevo, cambio de etiqueta— Gmail publica una notificación en ese tema, que la reenvía a tu webhook de push. Tu webhook luego llama usuarios.historial.listar con un almacenado historialId cursor para recuperar el delta del mensaje real. La notificación de Pub/Sub en sí misma solo contiene el correo electrónico del usuario y un historyId nuevo, no el contenido del mensaje.
usuarios.ver registra una suscripción de notificación push para un buzón de Gmail y devuelve una línea base de historyId. Es el punto de entrada que conecta Gmail a su tema de Pub/Sub. usuarios.historial.listar es el endpoint de reconciliación que llamas después de recibir una notificación push de Gmail para obtener los cambios reales (adiciones, eliminaciones de mensajes, cambios de etiquetas) que ocurrieron desde tu historial guardado historyId. Watch le dice a Gmail dónde enviar las alertas. History te dice qué cambió realmente.
los puntos finales de observación de la API de Gmail caducan después de 7 días. La mejor práctica es ejecutar un trabajo diario de cron en lugar de cada 6 o 7 días, por lo que se tiene un búfer de varios días contra fallos transitorios. La renovación del certificado es idempotente: una nueva usuarios.ver La llamada simplemente reinicia el temporizador y devuelve una base de datos de historial recién creada. La expiración ocurre silenciosamente: no hay notificaciones de advertencia, por lo que un cron fallido significa eventos perdidos sin errores en ninguno de los lados.
La causa más común es una permiso IAM faltante. Gmail utiliza la cuenta de servicio gmail-api-push@system.gserviceaccount.com para publicar en tu tema de Pub/Sub. Sin el Publicador de Pub/Sub papel en tu tema para esta cuenta, usuarios.ver tiene éxito, pero nunca se entregan notificaciones. Otras causas: el tipo de suscripción es "Pull" en lugar de "Push", certificado TLS no válido en tu punto final de webhook, o tu punto final devuelve respuestas que no son 2xx, lo que hace que Pub/Sub deje de entregar.
En historialId es un entero monotónicamente creciente que Gmail asigna a cada evento de cambio de buzón. Actúa como un cursor de sincronización incremental. Cuando te registras usuarios.ver, Gmail devuelve un `historyId` de referencia que representa el estado actual. Las notificaciones push posteriores de Gmail incluyen un nuevo `historyId`. Pasas tu `historyId` almacenado (anterior) como inicioIdHistorial a usuarios.historial.listar para obtener todos los cambios entre los dos puntos. Debes almacenar el último historyId por usuario autenticado en tu base de datos. Los HistoryIds de más de 7 días devuelven un error 404.
No directamente a través de la API de Gmail: Pub/Sub es el canal de entrega requerido para las notificaciones push de Gmail. Sin embargo, puedes omitir por completo la infraestructura de GCP utilizando una API de correo electrónico unificada como Unipile, que actúa como intermediario técnico independiente en nombre de cada usuario autenticado, abstrae la capa Pub/Sub y entrega notificaciones push de Gmail a tu webhook con una carga útil normalizada. No se requiere ningún proyecto de GCP, ninguna concesión de IAM, ni ningún cron de renovación de watch.
Ejecutar un trabajo diario de cron que llama usuarios.ver para todos los usuarios autenticados activos. Almacene el historyId devuelto como la nueva línea de base y actualice la marca de tiempo de caducidad almacenada. Maneje los errores por usuario sin abortar el lote: un 401 significa que el token de actualización de OAuth fue revocado (el usuario debe volver a autorizar), un 404 significa que la vigilancia ya expiró. Nunca espere a la caducidad de 7 días para renovar; trate la ejecución diaria como mantenimiento, no como una solución reactiva.
Las notificaciones push de la API de Gmail tienen un límite aproximado de 1 evento por segundo por usuario autenticado. Las ráfagas por encima de este umbral se agrupan o se retrasan, no se descartan. El usuarios.historial.listar la llamada cuesta 5 unidades de cuota y usuarios.ver cuesta 100 unidades por llamada. La cuota diaria predeterminada de la API de Gmail es de 1 millón de unidades por proyecto. Para obtener un desglose completo de los límites por método y los procedimientos para aumentar las cuotas, consulta nuestra Guía de límites de frecuencia de la API de Gmail.
¿Necesitas ayuda para configurar las notificaciones push de la API de Gmail para tu aplicación? Nuestro equipo puede guiarte en el proceso.
ES 
EN 
FR 
DE 
IT 
BR 
NL 
PL 
TR