guía · api de gmail

¿Cómo debe implementar un equipo de producto la API de Gmail de forma segura?

Implemente la API de Gmail como un acceso delegado a un buzón de Gmail concreto, no como una credencial genérica de entrega de correo. Elija el alcance de OAuth más reducido que permita la función, proteja el estado de autorización y los tokens de actualización, y limite cada buzón a su tenant. Construya los mensajes con una biblioteca madura de mensajes de Internet, registre el ID de mensaje de Gmail devuelto y sincronice los cambios mediante Pub/Sub junto con los registros de historial. Trate la suplantación mediante cuentas de servicio como una decisión del administrador de Workspace. Por último, mantenga la aceptación por la API, la entrega al servidor receptor y la llegada a la bandeja de entrada como resultados separados.

Elija el modelo de buzón antes de escribir código

La API de Gmail opera sobre el buzón de Gmail de un usuario. Es adecuada cuando un producto debe leer ese buzón, organizar sus etiquetas e hilos, crear borradores, enviar como el usuario autorizado o sincronizar los cambios del buzón. Esa autoridad es considerablemente más amplia que llamar a una API de correo de aplicación desde un dominio de producto verificado. Empiece por definir la tarea exacta sobre el buzón y quién concede el acceso. Un producto orientado a usuarios normalmente usa el consentimiento OAuth para cada cuenta de Google conectada. Una automatización interna de Google Workspace podría usar, en cambio, la delegación en todo el dominio aprobada por un administrador. Si el único requisito es enviar recibos, enlaces de verificación, alertas u otros mensajes desencadenados por el producto desde un dominio que controla la empresa, evite por completo el acceso al buzón y evalúe una API de correo transaccional. Esta decisión de arquitectura reduce los accesos innecesarios antes de que algún control de seguridad o pantalla de consentimiento tenga que compensarlos.

Autorice el alcance práctico más reducido

Configure un cliente OAuth para el tipo de aplicación correcto, use un URI de redirección registrado exacto y vincule la respuesta de autorización a la sesión del navegador que la inició mediante un valor state impredecible. Solicite el acceso en contexto, cuando el usuario active la función que lo necesita. Para una integración que solo envía, `https://www.googleapis.com/auth/gmail.send` es más reducido que los alcances que leen o modifican el buzón. Google clasifica `gmail.send` como sensible, mientras que alcances como `gmail.readonly`, `gmail.compose` y `gmail.modify` son restringidos. Una aplicación pública que use accesos sensibles o restringidos puede requerir la verificación de OAuth, y el almacenamiento o la transmisión en el servidor de datos de alcances restringidos puede activar requisitos adicionales de evaluación de seguridad. Solicite acceso sin conexión solo cuando el trabajo en segundo plano sea realmente necesario. Cifre los tokens de actualización, asocie cada token a un único tenant interno y a un sujeto de Google, no lo exponga nunca en el código del navegador ni en los registros, y ofrezca una vía de desconexión probada que elimine las credenciales locales y detenga el procesamiento en segundo plano.

Entienda las cuentas de servicio y la delegación en todo el dominio

Una cuenta de servicio es una identidad de aplicación, no una bandeja de entrada de Gmail lista para usar. Por sí sola no obtiene acceso a los mensajes de los empleados. Para los datos de usuario de Google Workspace, un superadministrador debe autorizar explícitamente el ID de cliente numérico de la cuenta de servicio y una lista exacta de alcances de OAuth mediante la delegación en todo el dominio. La aplicación solicita entonces credenciales delegadas para un usuario concreto, y cada llamada a la API actúa con los permisos de ese usuario dentro de los alcances autorizados. Mantenga explícito el sujeto suplantado en los datos de las tareas y en los registros de auditoría para que un worker en segundo plano no pueda cambiar de buzón en silencio. Use cuentas de servicio separadas para cargas de trabajo sustancialmente distintas, evite las claves privadas descargables cuando el entorno de ejecución pueda usar credenciales gestionadas y revise periódicamente las concesiones en todo el dominio. Las cuentas de Gmail de consumo no tienen un administrador de Workspace que pueda conceder esta delegación a toda la organización, así que use el consentimiento OAuth del usuario para esas cuentas.

Envíe mensajes sin perder el control ni la trazabilidad

Gmail acepta un mensaje de correo de Internet completo en el campo `raw`, codificado en base64url, mediante `users.messages.send`; un producto también puede crear un borrador y enviarlo más tarde. Use una biblioteca de mensajes mantenida para generar los campos From, To, Cc, Bcc, Subject, Date y Message-ID, el texto, el HTML y la estructura de adjuntos, en lugar de unir líneas de encabezado a mano. Valide los destinatarios y el contenido antes de codificar, rechace la inyección de encabezados y establezca límites de tamaño explícitos. Haga que la acción del producto sea idempotente antes de llamar a Gmail: guarde una clave estable del evento de la aplicación, el sujeto del buzón previsto y un estado del intento de envío. Tras una respuesta correcta, guarde el ID de mensaje y el ID de hilo que devuelve Gmail junto con ese evento. Si el cliente agota el tiempo de espera después de transmitir la solicitud, concilie el estado del buzón antes de reintentar, porque es posible que el mensaje ya se haya aceptado. Un reintento a ciegas puede producir un correo duplicado aunque se haya perdido la respuesta original. Use la creación de borradores con revisión humana cuando el contenido o los destinatarios requieran aprobación.

Sincronice los cambios del buzón con los registros de historial

En una integración de buzón del lado del servidor, un watch de Gmail publica señales de cambio a través de Google Cloud Pub/Sub. La notificación es un aviso para sincronizar, no un payload de correo completo. Guarde el history ID actual y la caducidad de la respuesta del watch, confirme las notificaciones rápidamente y llame a `users.history.list` desde el último history ID confirmado correctamente para descubrir cambios en mensajes y etiquetas. Obtenga solo los mensajes que necesita la función y avance el punto de control después de que las escrituras locales se completen. Las notificaciones pueden llegar con retraso o duplicadas, así que haga que el procesamiento de mensajes y de historial sea idempotente. Gmail exige renovar el watch de un buzón al menos cada siete días y recomienda renovarlo a diario; programe la renovación con bastante antelación a la caducidad y genere alertas ante los fallos. Si un history ID guardado está fuera del rango disponible en Gmail, la API devuelve HTTP 404. Trátelo como una vía de recuperación definida: haga una sincronización completa controlada, establezca un nuevo punto de control y reanude el procesamiento incremental en lugar de reintentar indefinidamente con el history ID no válido.

Siga un flujo de implementación y verificación por etapas

Primero, documente si la función envía, lee, modifica o vigila el correo, y asigne a cada operación su alcance de OAuth mínimo. Segundo, cree proyectos de Google Cloud o clientes OAuth separados para desarrollo y producción, con URI de redirección exactos y responsables de credenciales designados. Tercero, implemente la autorización con validación de state, acceso sin conexión solo cuando sea necesario, almacenamiento cifrado de tokens, revocación de tokens y comprobaciones de acceso a nivel de tenant. Cuarto, haga pruebas con buzones controlados: conecte, actualice un token de acceso caducado, revoque el consentimiento, vuelva a conectar, envíe una vez, simule un tiempo de espera ambiguo y confirme que se evitan los duplicados. Quinto, si recibe cambios, aprovisione los permisos de Pub/Sub, inicie un watch, procese el historial de forma incremental, fuerce una recuperación con un punto de control obsoleto y verifique la renovación del watch. Sexto, agregue colas de trabajo por usuario, backoff exponencial acotado, clasificación estructurada de errores y registros de auditoría que omitan por defecto el cuerpo de los mensajes y los tokens. Antes del lanzamiento, complete cualquier verificación y revisión de seguridad que exija Google, publique información precisa sobre el uso de los datos y ensaye la rotación de credenciales y la eliminación de datos de usuario.

Planifique las cuotas, los reintentos y los fallos parciales

Gmail mide el uso de la API en unidades de cuota, no solo en número de solicitudes. La página de cuotas de Google enumera 1.200.000 unidades por minuto por proyecto y 6.000 unidades por minuto por usuario y proyecto. Enumera `messages.send`, `drafts.send` y `watch` con 100 unidades cada uno, y un límite de 500 destinatarios por mensaje. Los límites de envío de usuarios independientes de Gmail se siguen aplicando en los clientes de API, web y SMTP. Trate la consola de Cloud y la documentación actual como entradas de configuración de tiempo de ejecución en lugar de codificar de forma fija los límites publicados en la lógica de negocio. Serialice o ponga en cola de forma justa el trabajo por buzón, limite la simultaneidad y reintente solo respuestas transitorias con backoff exponencial con jitter y una fecha límite finita. No reintente errores de autorización, política, destinatario no válido o mensaje malformado como si fueran problemas de capacidad. Un lote multipart reduce la sobrecarga de conexión, pero cada llamada interna sigue consumiendo cuota y puede fallar de forma independiente.

Mantenga separadas la aceptación, la entrega y la llegada a la bandeja de entrada

Una llamada correcta a `messages.send` significa que Gmail aceptó la solicitud de API autorizada y devolvió un recurso Message de Gmail. No demuestra que el servidor de correo de cada destinatario haya aceptado el mensaje, ni puede establecer cómo lo clasificó un sistema receptor. La entrega al servidor del destinatario significa que el sistema de destino asumió la responsabilidad SMTP. La llegada a la bandeja de entrada es un resultado de filtrado posterior, como la bandeja principal, promociones, cuarentena o spam. Por lo tanto, la API de buzón de Gmail no sustituye al flujo de eventos de un proveedor cuando un producto necesita telemetría de entregas, rebotes o quejas para el correo transaccional. Conserve el ID de mensaje de Gmail para la conciliación, pero describa con precisión el estado visible para el usuario como enviado o aceptado por Gmail, a menos que otra evidencia respalde la entrega. La autenticación, que los destinatarios esperen el mensaje, la calidad del contenido, el comportamiento de envío y la política del destino afectan al tratamiento posterior. Una respuesta de la API no puede determinar ni garantizar la carpeta final del buzón del destinatario.

Sepa cuándo una API de correo transaccional encaja con otra tarea

Use Gmail API cuando el producto necesite acceso autorizado al buzón de Gmail de una persona u organización, incluidos hilos, etiquetas, borradores o sincronización de buzones. Una API de correo transaccional se ajusta a una arquitectura diferente: mensajes activados por la aplicación enviados desde dominios que controla la organización, sin autoridad delegada para leer el buzón de Gmail de un usuario. Un producto puede usar ambos tipos de sistemas cuando los límites son explícitos, por ejemplo, Gmail OAuth para leer el buzón conectado de un agente de soporte y un proveedor transaccional verificado por separado para enviar recibos de producto. Mantenga separadas las credenciales, el consentimiento, los almacenes de mensajes, las políticas de reintento y los registros de auditoría para que la autoridad sobre el buzón no se filtre al envío de toda la aplicación y una credencial transaccional no pueda leer el Gmail de un usuario.

Preguntas frecuentes

¿Puede una cuenta de servicio acceder a cualquier buzón de Gmail?

No. Una cuenta de servicio no recibe automáticamente acceso a los datos de usuario de Gmail. Un superadministrador de Google Workspace debe conceder la delegación en todo el dominio a su ID de cliente numérico y a los alcances aprobados, tras lo cual la aplicación suplanta explícitamente a un usuario de esa organización. Para las cuentas de Gmail de consumo, use en su lugar el consentimiento OAuth del usuario.

¿Qué alcance de OAuth debe solicitar una integración de Gmail que solo envía?

Empiece por evaluar `https://www.googleapis.com/auth/gmail.send`, que permite enviar en nombre del usuario sin conceder la lectura general del buzón. Confirme que ningún requisito del producto necesita realmente borradores, lectura de mensajes, etiquetas o modificaciones antes de solicitar un alcance más amplio, y tenga en cuenta las reglas de verificación de Google para los alcances sensibles.

¿Un envío correcto con la API de Gmail significa que el mensaje se entregó?

No. Confirma que Gmail aceptó la operación de API autorizada y devolvió un registro del mensaje. La aceptación por el servidor receptor y la llegada a la bandeja de entrada son estados posteriores independientes. No etiquete el mensaje como entregado ni prometa la llegada a la bandeja de entrada a menos que otra señal confiable respalde esa conclusión.

¿Las notificaciones push de Gmail contienen el mensaje nuevo completo?

No. Una notificación de Pub/Sub indica que el estado del buzón cambió e incluye información para continuar la sincronización. La aplicación debe consultar el historial de Gmail a partir de su history ID guardado, obtener los datos de mensaje necesarios, procesarlos de forma idempotente y luego avanzar su punto de control.

¿Con qué frecuencia se debe renovar el watch de un buzón de Gmail?

Google exige llamar a `watch` al menos una vez cada siete días y recomienda renovarlo a diario. Guarde la caducidad devuelta, renueve antes de que llegue, monitoree los fallos y mantenga una tarea de sincronización de respaldo para que una renovación omitida no genere en silencio un vacío de datos sin límite.

¿Cuándo debe un equipo usar una API de correo transaccional en lugar de la API de Gmail?

Use una API de correo transaccional cuando la tarea sea enviar correo desencadenado por la aplicación desde dominios que controla la organización y ninguna función necesite acceder al buzón de Gmail de una persona. Use la API de Gmail cuando el producto necesite específicamente mensajes, hilos, etiquetas, borradores, configuración o permisos de envío como (send-as) de un buzón delegado.

Fuentes

Siga aprendiendo

Guía de implementación de una API de correo electrónico para equipos de productoDiseñe una integración segura con una API de correo mediante dominios verificados, envíos en cola, identificadores estables, reintentos controlados, eventos de entrega, supresiones y aislamiento por tenant.