Alcances de la API de Gmail Explicados: Elija los Permisos Adecuados para su Aplicación

Unipile - Envía correos electrónicos a través de la API en Python TOC
Unipile - Ámbitos de Gmail API Héroe
Guía de la API de Gmail

Alcances de la API de Gmail Explicados: Elige el Permisos correctos para tu aplicación

Todos los alcances de la API de Gmail documentados: desde gmail.lectura a mail.google.com. Comprende los 3 niveles de sensibilidad, elige el alcance mínimo que tu aplicación realmente necesita y envía tu flujo de OAuth más rápido.

gmail-oauth-scopes.js
// Solicitar los alcances de la API de Gmail en el flujo de OAuth const ÁMBITOS = [ 'https://www.googleapis.com/auth/gmail.readonly', 'https://www.googleapis.com/auth/gmail.send', 'https://www.googleapis.com/auth/gmail.labels', ]; const urlDeAutenticación = oauth2Cliente.generarUrlDeAutenticación({ tipo_acceso: 'desconectado', alcance ÁMBITOS, solicitud 'consentimiento', });
gmail.lectura Restringido
gmail.enviar Sensible
gmail.etiquetas No sensible
Fundamentos

¿Qué son los alcances de la API de Gmail?

Antes de escribir una sola línea de código OAuth, necesitas entender qué son los alcances de la API de Gmail y por qué elegir el incorrecto puede impedir que tu aplicación pase a producción. Esta sección te proporciona el conocimiento fundamental en menos de dos minutos.

Definición

Alcances de la API de Gmail son cadenas de permisos de OAuth 2.0 que definen exactamente a qué recursos de Gmail puede acceder tu aplicación en nombre de un usuario. Cuando un usuario autoriza tu aplicación, Google presenta una pantalla de consentimiento que enumera los ámbitos de la API de Gmail que tu aplicación solicitó. El usuario otorga o deniega el acceso basándose en esos ámbitos. Una vez concedido, tu token de acceso se limita exactamente a las acciones que esos ámbitos permiten, nada más.

Límite de seguridad

Los alcances de la API de Gmail crean un límite estricto en cuanto a lo que tu token puede hacer. Incluso si tu servidor se ve comprometido, un atacante con un gmail.lectura El token no puede enviar ni eliminar correos electrónicos. Los ámbitos son aplicados por Google en el servidor.

Puerta de verificación de Google

Los alcances restringidos de la API de Gmail requieren que tu aplicación pase la evaluación de seguridad de Google antes de poder usarlos en producción con más de 100 usuarios de prueba. La elección incorrecta del alcance puede alargar tu cronograma de lanzamiento semanas o meses.

Señal de confianza del usuario

Solicitar más permisos de la API de Gmail de los que necesita tu aplicación activa una advertencia de "Esta aplicación quiere acceso amplio a tu Cuenta de Google". Los ámbitos mínimos de la API de Gmail producen una pantalla de consentimiento más simple, lo que aumenta la conversión y la confianza del usuario.

Omite por completo la gestión del alcance. Unipile maneja OAuth y alcances de Gmail internamente: tu equipo se enfoca en la lógica del producto, no en las cadenas de permisos.

Constrúyelo con Unipile
Niveles de sensibilidad del ámbito de Gmail de Unipile
Clasificación de Alcance

Los 3 niveles de sensibilidad explicados

Google clasifica todos los ámbitos de la API de Gmail en 3 niveles de sensibilidad. Cada nivel determina los requisitos de verificación antes de que tu aplicación pueda salir en vivo. Comprender esta clasificación es la decisión más importante que tomas al planificar tu integración de Gmail.

No sensible
Alcances no confidenciales

El nivel de riesgo más bajo. Estos ámbitos acceden a datos de Gmail limitados y no personales. Google no requiere una evaluación de seguridad formal para usarlos en producción.

Verificación Revisión estándar de aplicaciones OAuth
Usuarios de prueba Ilimitado una vez que la aplicación sea verificada
Ejemplos
gmail.etiquetas gmail.addons.current.action.compose
Sensible
Alcances sensibles

Nivel de riesgo medio. Estos ámbitos acceden a datos de mensajes de Gmail que podrían exponer información personal. Se requiere verificación adicional antes de su uso en producción.

Verificación Verificación de la aplicación de Google OAuth requerida
Usuarios de prueba Hasta 100 mientras está en pruebas
Ejemplos
gmail.enviar gmail.addons.current.message.readonly
Restringido
Ámbito restringido

Nivel de riesgo más alto. Estos alcances otorgan acceso amplio o sensible a datos de Gmail. Google requiere una evaluación de seguridad formal por parte de un auditor externo aprobado.

Verificación Evaluación anual de seguridad (aprox. 1 000–4 000 € al año)
Usuarios de prueba Hasta 100 mientras está en pruebas
Ejemplos
gmail.lectura gmail.modificar mail.google.com/
Criterios No sensible Sensible Restringido
Accede al cuerpo del mensaje No A veces
Se requiere una evaluación de seguridad No No
Revisión de aplicación requerida
Recertificación anual No No
Nivel de advertencia de la pantalla de consentimiento Estándar Estándar + divulgación Advertencia de acceso amplio
Costo típico de verificación Gratis Gratis ~1 TP4T500/año (tasador)
Accede al cuerpo del mensaje
No sensibleNo
SensibleA veces
Restringido
Se requiere una evaluación de seguridad
No sensibleNo
SensibleNo
Restringido
Revisión de aplicación requerida
No sensible
Sensible
Restringido
Recertificación anual
No sensibleNo
SensibleNo
Restringido
Nivel de advertencia de la pantalla de consentimiento
No sensibleEstándar
SensibleEstándar + divulgación
RestringidoAdvertencia de acceso amplio
Costo típico de verificación
No sensibleGratis
SensibleGratis
Restringido~1 TP4T500/año (tasador)
Referencia completa

Referencia completa de ámbitos de la API de Gmail

La lista completa de ámbitos de la API de Gmail, agrupada por nivel de sensibilidad. Utilice esta tabla como su única referencia al elegir los permisos de la API de Gmail para su aplicación. Los ámbitos marcados con "2026" reflejan las últimas adiciones a la lista de ámbitos de Google.

URI del ámbito Nivel de acceso Lo que accede Cuándo usar
gmail.addons.current.action.compose No sensible Permite que los complementos compongan y envíen correos electrónicos durante una acción de redacción. Complementos de Gmail que redactan o envían correos electrónicos en nombre del usuario dentro de la ventana de redacción
gmail.addons.current.message.action No sensible Permite que los complementos vean el correo electrónico actual durante una acción de mensaje Complementos de Gmail que reaccionan a una acción de mensaje (archivar, etiquetar) en el contexto del mensaje
gmail.etiquetas 2026 No sensible Ver y editar etiquetas (crear, renombrar, eliminar), pero no contenido de mensajes Aplicaciones que organizan el correo electrónico con etiquetas sin necesidad de leer el cuerpo del mensaje
URI del ámbito Nivel de acceso Lo que accede Cuándo usar
gmail.addons.current.message.metadata Sensible Encabezados y metadatos de correo electrónico (De, Para, Asunto, Fecha) en el contexto de un complemento - no el cuerpo del mensaje Complementos que muestran información contextual basada en el remitente o el tema sin leer el cuerpo
gmail.addons.current.message.readonly Sensible Acceso de lectura completo al correo electrónico actual, incluyendo cuerpo y archivos adjuntos, en contexto de complemento Complementos que analizan o extraen datos del mensaje abierto actualmente
gmail.enviar Sensible Enviar correo electrónico en nombre del usuario autenticado - sin acceso de lectura o modificación Aplicaciones que solo envían correos electrónicos transaccionales o de prospección y no necesitan leer la bandeja de entrada
URI del ámbito Nivel de acceso Lo que accede Cuándo usar
mail.google.com/ Restringido Acceso completo al buzón de correo: leer, redactar, enviar y eliminar permanentemente correos electrónicos y configuraciones Solo cuando necesitas todas las capacidades de Gmail en un solo ámbito, típicamente integraciones heredadas.
gmail.lectura Restringido Acceso de solo lectura a todos los mensajes, hilos, etiquetas y configuraciones - no se pueden enviar ni modificar Herramientas de análisis, archivo, búsqueda o inteligencia de correo electrónico que solo leen datos de la bandeja de entrada
gmail.redactar Restringido Crear y gestionar borradores, y enviar esos borradores - sin acceso a correos electrónicos existentes Herramientas de gestión de borradores, redactores de correos electrónicos o aplicaciones que ponen en cola los correos electrónicos antes de enviarlos
gmail.insertar 2026 Restringido Inserta mensajes en la bandeja de entrada de Gmail solamente - no puede leer ni enviar correos electrónicos existentes Herramientas o sistemas de migración que importan correos electrónicos a Gmail desde fuentes externas
gmail.modificar Restringido Leer, redactar, enviar y administrar correos electrónicos y etiquetas - no se pueden eliminar permanentemente Clientes de correo electrónico con todas las funciones, herramientas de sincronización de CRM, integraciones de helpdesk que necesitan leer+enviar+etiquetar
metadatos de gmail Restringido Solo encabezados y etiquetas - sin acceso al cuerpo del correo ni a los archivos adjuntos Aplicaciones que categorizan o enrutan correos electrónicos basándose en metadatos sin leer contenido privado
gmail.configuración.básica Restringido Gestionar la configuración básica de Gmail: filtros, reglas de reenvío, configuración POP/IMAP Herramientas de productividad de correo electrónico que configuran el enrutamiento o filtrado de Gmail en nombre de los usuarios
gmail.configuración.compartir Restringido Gestión de configuraciones sensibles: alias de envío como, delegados, respuestas de vacaciones (solo administrador de dominio) Herramientas de administrador del espacio de trabajo solamente - requiere privilegios de administrador de dominio para habilitar

No gestiones estos ámbitos de la API de Gmail manualmente. La integración de Gmail de Unipile maneja las solicitudes de alcance OAuth, el refresco de tokens y los flujos de reautorización automáticamente en las cuentas vinculadas de sus usuarios.

Crea tu aplicación de Gmail
Matriz de Casos de Uso

¿Qué ámbito de la API de Gmail necesitas?

El principio más importante en la selección de los ámbitos de la API de Gmail es el principio de acceso mínimo: solicita solo los permisos de la API de Gmail que tu aplicación realmente necesita. Esta tabla mapea los casos de uso comunes con el ámbito mínimo recomendado, ayudándote a evitar sobrecarga de verificación innecesaria y a proteger la confianza de los usuarios.

Caso práctico Alcance mínimo Nivel de Verificación Notas
Enviar correos electrónicos solamente (no leer bandeja de entrada) gmail.enviar Sensible Ideal para herramientas transaccionales o de alcance. Sin acceso a mensajes existentes.
Leer bandeja de entrada para análisis o buscar gmail.lectura Restringido Acceso completo de lectura a todos los mensajes y configuraciones. Requiere evaluación de seguridad anual.
Cliente de correo electrónico completo (leer + enviar + etiquetar) gmail.modificar Restringido Preferido sobre mail.google.com/ ya que excluye la eliminación permanente. Cubre la mayoría de los casos de uso de CRM y helpdesk.
Archivar o hacer copia de seguridad de correos electrónicos permanentemente mail.google.com/ Restringido Úsalo solo cuando realmente necesites acceso de eliminación. Activa la advertencia de consentimiento más amplia de Google.
Organizar etiquetas solamente gmail.etiquetas No sensible Novedad en 2026. Permisos mínimos para la gestión de etiquetas sin leer mensajes.
Gestión de borradores (cola antes de enviar) gmail.redactar Restringido Acceso a borradores y capacidad de envío, pero sin acceso de lectura a mensajes existentes.
Enrutamiento o categorización de metadatos metadatos de gmail Restringido Solo encabezados y etiquetas: sin acceso al cuerpo del mensaje. Ideal para motores de enrutamiento que respetan la privacidad de los mensajes.
Migración / importación de correo electrónico a Gmail gmail.insertar Restringido Novedad en 2026. Acceso de solo inserción: alternativa mejor definida para mail.google.com/ para importar herramientas.
Configurar filtros y reenvío de Gmail gmail.configuración.básica Restringido Gestionar filtros, etiquetas, reglas de reenvío. Sin acceso al cuerpo del mensaje.
Complemento de Gmail: mostrar contexto del remitente gmail.addons.current.message.metadata Sensible Encabezados solo en el contexto del complemento. Evita el acceso completo de lectura de mensajes.
Combina los ámbitos solo cuando sea necesario

Puedes combinar varios ámbitos de la API de Gmail en una única solicitud de OAuth (por ejemplo, gmail.enviar + gmail.etiquetas), pero cada ámbito se suma a la divulgación en la pantalla de consentimiento. Siempre audita tu lista de ámbitos antes de ir a producción. Si estás creando un producto de sincronización completa de Gmail, el Guía de la API de correo electrónico de OAuth cubre el flujo completo, incluida la gestión de tokens y la reautorización de ámbitos.

Proceso de Verificación

Verificación de alcance restringido: Qué significa para tu aplicación

Si tu aplicación necesita algún ámbito restringido de la API de Gmail, incluyendo gmail.lectura, gmail.modificaro mail.google.com/ - debes completar el proceso de evaluación de seguridad de Google antes de lanzar a más de 100 usuarios de prueba. Aquí te mostramos en qué consiste ese proceso y cómo minimizar la carga.

1
Registra tu aplicación OAuth en la Consola de Google Cloud

Crea un proyecto, habilita la API de Gmail y configura la pantalla de consentimiento de OAuth. Completa todos los campos obligatorios: nombre de la aplicación, correo electrónico de soporte, dominios autorizados y URL de la política de privacidad. Este paso es obligatorio para cualquier nivel de alcance de la API de Gmail.

2
Enviar para revisión de la aplicación con ámbitos restringidos declarados

En la pantalla de consentimiento de OAuth, haz clic en "Preparar para la verificación". Declara cada ámbito restringido de la API de Gmail y proporciona una justificación que explique por qué tu aplicación lo necesita. El equipo de Google revisa esto antes de dirigirte a un evaluador de seguridad.

3
Completar la evaluación de seguridad de terceros

Google deriva las aplicaciones de alcance restringido a un evaluador autorizado (Leviathan Security, Coalfire, etc.). La evaluación cuesta aproximadamente 1 450 € al año. Debes proporcionar una demostración, explicar las prácticas de tratamiento de datos y superar una revisión técnica de tu implementación de OAuth.

4
Recertificación anual para acceso continuo

Los ámbitos restringidos de la API de Gmail requieren una recertificación anual. Si se pierde la ventana de renovación, Google puede revocar el acceso de producción de su aplicación. Planifique este costo recurrente y el ciclo de cumplimiento desde el primer día de la arquitectura de su integración de Gmail.

Cómo evitar o minimizar la verificación de alcance restringido

Elegir gmail.enviar sobre gmail.modificar cuando tu aplicación solo envía correos electrónicos y no necesita leer la bandeja de entrada. gmail.enviar es un alcance sensible (no restringido) y omite por completo la evaluación de seguridad.

Utilice metadatos de gmail en vez de gmail.lectura si su aplicación enruta o clasifica correos electrónicos sin leer el contenido del cuerpo. Aún así, necesita verificación, pero el alcance es más reducido y más fácil de justificar ante Google.

Utilice una plataforma que ya tenga verificación de Google. Cuando construyes sobre Integración de Gmail de Unipile, tu aplicación se beneficia de las credenciales OAuth preverificadas de Unipile, por lo que no necesitas pasar tú mismo por la evaluación de alcance restringido. Este es el camino más rápido a producción para la mayoría de los productos SaaS.

Mantente en la ventana de prueba de 100 usuarios durante el desarrollo temprano. Puedes probar los ámbitos restringidos de la API de Gmail con hasta 100 cuentas de Google sin completar la verificación completa. Agrega cuentas de prueba en la configuración de la pantalla de consentimiento de OAuth de Google Cloud Console.

Omita el proceso de verificación de Google por completo. El OAuth de Gmail alojado de Unipile ya está verificado para ámbitos restringidos de la API de Gmail: tus cuentas enlazadas se conectan de inmediato sin una evaluación adicional.

Empieza a construir hoy
Implementación

Cómo solicitar ámbitos de la API de Gmail en tu flujo de OAuth

Una vez que sepa qué ámbitos de OAuth de Gmail necesita su aplicación, los declara al generar la URL de autorización. Aquí tienes ejemplos de código que funcionan tanto en Node.js como en Python que muestran exactamente cómo pasar los permisos de la API de Gmail a la pantalla de consentimiento de OAuth.

gmail-scopes-node.js
// Node.js — Ámbitos de la API de Gmail en el flujo de OAuth // Usa google-auth-library (cliente oficial de Google) const { OAuth2Client } = require('google-auth-library'); const oauth2Cliente = new OAuth2Client( process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, process.env.REDIRECT_URI ); // Define los alcances de la API de Gmail que tu aplicación necesita Principio: solicitar el alcance mínimo requerido const ÁMBITOS = [ 'https://www.googleapis.com/auth/gmail.readonly', // restringido 'https://www.googleapis.com/auth/gmail.send', // sensible 'https://www.googleapis.com/auth/gmail.labels', // no sensible ]; // Generar la URL de autorización de OAuth const authUrl = oauth2Cliente.generarUrlDeAutenticación({ tipo_acceso: 'desconectado', // solicitar token de actualización alcance: ALCANCES, solicitud 'consentimiento', forzar el consentimiento para obtener el token de actualización }); consola.log('Redirigir al usuario a:', authUrl); // Después de que el usuario autoriza, canjea el código por tokens async function obtenerTokens(código) { const { tokens } = await oauth2Cliente.obtenerToken(código); oauth2Cliente.establecerCredenciales(tokens); return tokens; }
URL de autorización generada - ámbitos de OAuth de Gmail declarados
gmail-scopes.py
# Python — Ámbitos de la API de Gmail en el flujo de OAuth # utiliza google-auth-oauthlib (biblioteca oficial de Google) from google_auth_oauthlib.flow import FlujoDeAplicacionInstalada from google.oauth2.credenciales import Credenciales from google.auth.transport.requests import Solicitud import os # Definir los ámbitos de la API de Gmail: solicita solo lo que necesites ÁMBITOS = [ 'https://www.googleapis.com/auth/gmail.readonly', Restringido a # 'https://www.googleapis.com/auth/gmail.send', sensible a # 'https://www.googleapis.com/auth/gmail.labels', # no sensible ] def obtener_credenciales_gmail(): créditos = Ninguno # Cargar el token existente si está disponible si os.path.existe('token.json'): credenciales = Credenciales.del_archivo_de_usuario_autorizado( 'token.json', ÁMBITOS ) # Actualizar o solicitar nuevas credenciales si no acreditaciones o no credenciales.válido: si acreditaciones y créditos.expirados y creds.refresh_token: créditos.actualizar(Solicitud()) si no: #: Activar la pantalla de consentimiento de OAuth con los ámbitos declarados flujo = FlujoAppInstalada.desde_archivo_de_secretos_del_cliente( 'credenciales.json', ÁMBITOS ) credenciales = flujo.correr_servidor_local(puerto=0) #: token persistente para ejecuciones futuras con abrir('token.json', 'doble ve') como token: token.escribir(credenciales.a_json()) return acreditaciones
ámbitos de OAuth de Gmail declarados: token persistido en disco

Importante: En consentimiento' (Node.js) o correr_servidor_local call (Python) fuerza que aparezca la pantalla de consentimiento de Google incluso si el usuario ha autorizado previamente. Esto es necesario para obtener de forma fiable un token de actualización. Sin un token de actualización, tu token de acceso expira después de 1 hora y los usuarios deben autorizar nuevamente. Para una guía completa sobre cómo manejar la actualización de tokens y la reautorización de ámbitos, consulta la Guía de la API de correo electrónico de OAuth y el Documentación de Google OAuth de Unipile.

Conformidad

Principio de Alcance Mínimo y Cumplimiento

El principio de alcance mínimo no es solo una recomendación de Google, sino que afecta directamente su cumplimiento con el RGPD y SOC 2. Solicitar permisos excesivos de la API de Gmail crea riesgos innecesarios de exposición de datos y complica sus acuerdos de procesamiento de datos con los usuarios finales.

Privilegio mínimo por diseño

El principio de alcance mínimo refleja el concepto de seguridad de mínimo privilegio. Tu integración de la API de Gmail debería solicitar ámbito de la API de Gmail con los permisos más bajos que habilita la función. Si tu CRM solo envía correos electrónicos de seguimiento, gmail.enviar es suficiente gmail.modificar es excesivo y crea un riesgo innecesario.

Pantalla de consentimiento clara

Google muestra los ámbitos de la API de Gmail que declares directamente en la pantalla de consentimiento. Ámbitos más amplios activan un lenguaje más alarmante ("Esta aplicación quiere acceder a toda tu bandeja de entrada de Gmail"). Ámbito mínimo de OAuth de Gmail crear pantallas de consentimiento más sencillas y menos intimidantes, lo que suele mejorar las tasas de conversión de autorizaciones entre un 15 % y un 30 % en los flujos de OAuth orientados al usuario.

Documentación de procesamiento de datos

Tu política de privacidad y el Acuerdo de Procesamiento de Datos (DPA) deben reflejar con precisión qué datos de Gmail accede tu aplicación. Si tu aplicación solicita gmail.lectura pero su política de privacidad solo menciona "envío de correos electrónicos", tiene una brecha de documentación del RGPD. Haga coincidir sus ámbitos declarados de la API de Gmail con sus prácticas de datos publicadas.

Auditoría de alcance como práctica recurrente

Los requisitos de alcance de la API de Gmail evolucionan a medida que se agregan o eliminan funciones. Realice una auditoría de alcance en cada versión principal: elimine cualquier permiso de la API de Gmail que su conjunto de características actual ya no requiera. Los alcances no utilizados en su declaración de OAuth son un pasivo de cumplimiento: representan acceso a datos que usted afirma necesitar pero que no utiliza.

GDPR
Alineación del RGPD con los ámbitos de Gmail
Limitación de finalidad: los ámbitos deben coincidir con la finalidad específica declarada a los usuarios
Minimización de datos: solicitud metadatos de gmail en vez de gmail.lectura cuando no se necesita acceso al cuerpo
Derechos de usuario: la revocación del token debe eliminar inmediatamente el acceso de tu aplicación a Gmail
Transparencia: el idioma de la pantalla de consentimiento debe coincidir con los datos que realmente procesas
SOC 2
Alineación de SOC 2 con los alcances de Gmail
Control de acceso: documente cada alcance de la API de Gmail y su justificación comercial en su política de control de acceso
Acceso lógico: la selección del alcance debe ser revisada y aprobada como parte de su proceso de gestión de cambios
Monitoreo: registrar todos los cambios de ámbito de Gmail en tu registro de auditoría
Gestión de proveedores: si utiliza una plataforma como Unipile, incluya su atestación de seguridad en su revisión de proveedores

Integración de Gmail lista para cumplimiento. La implementación de la API de Gmail de Unipile sigue el principio de alcance mínimo por defecto: tu aplicación solo solicita los ámbitos OAuth de Gmail necesarios para las funciones que habilitas.

Crea aplicaciones de Gmail que cumplan las normativas
Solución Unipile

Ámbitos de la API de Gmail con Unipile: Evita la complejidad de los ámbitos

Gestionar los ámbitos de la API de Gmail manualmente significa navegar por el proceso de verificación de Google, manejar la actualización de tokens ante cambios en los ámbitos y actualizar la documentación de procesamiento de datos cada vez que se agrega una nueva funcionalidad. Unipile abstrae todo esto, su equipo se enfoca en el producto, no en las cadenas de permisos.

Gmail Gmail
Outlook Outlook
IMAP IMAP
Gmail OAuth preverificado

Unipile cuenta con la verificación OAuth de Google para ámbitos restringidos de la API de Gmail. Tu aplicación se beneficia inmediatamente sin necesidad de completar una evaluación de seguridad separada. La recertificación anual es gestionada por el equipo de cumplimiento de Unipile.

Gestión automática de tokens

Unipile gestiona la actualización de tokens OAuth, la validación de ámbitos y los flujos de reautorización para cada una de las cuentas vinculadas de tus usuarios. Cuando Google actualiza los requisitos de ámbito, Unipile se adapta sin interrumpir tu integración.

API unificada entre proveedores

Las mismas llamadas a la API de Unipile funcionan para Gmail, Outlook e IMAP. Escribes tu funcionalidad de correo electrónico una vez y funciona en todos los proveedores, sin gestión de ámbitos de API de Gmail por separado para cada proveedor, sin ramificaciones de código específicas del protocolo.

Opción de OAuth de marca blanca

Para equipos que necesiten usar sus propias credenciales de Google, Unipile admite la configuración de OAuth con marca blanca. Tus usuarios verán tu marca en la pantalla de consentimiento mientras Unipile gestiona la declaración de ámbitos y el ciclo de vida de los tokens en segundo plano.

Alcance mínimo por defecto

La integración de Gmail de Unipile solicita solo los permisos de la API de Gmail necesarios para las funciones que habilita. Leer, enviar, sincronizar, cada capacidad se mapea al alcance más estrecho posible, manteniendo su perfil de cumplimiento limpio.

Ganchos web en tiempo real

Recibe nuevos mensajes de Gmail a medida que llegan a través de webhooks de Unipile. Sin sondeos ni gestión manual de suscripciones de Pub/Sub de Gmail. Funciona con el mismo token OAuth que tu aplicación ya utiliza para otras operaciones de la API de Gmail.

No se requiere evaluación de seguridad
Gmail, Outlook e IMAP en una sola API
Alineado con GDPR y SOC 2
Prueba gratuita de 14 días, no se requiere tarjeta
PREGUNTAS FRECUENTES

Preguntas frecuentes sobre los alcances de la API de Gmail

Preguntas frecuentes sobre los ámbitos de la API de Gmail, los ámbitos de OAuth de Gmail y el proceso de verificación, respondidas de forma concisa para desarrolladores que crean integraciones de Gmail.

01
¿Qué son los ámbitos de la API de Gmail?
Alcances de la API de Gmail son cadenas de permisos de OAuth 2.0 que definen exactamente a qué recursos de Gmail puede acceder tu aplicación en nombre de un usuario. Se declaran al generar la URL de autorización de OAuth y se muestran al usuario en la pantalla de consentimiento de Google. Una vez que un usuario otorga acceso, tu token se limita solo a las acciones que permiten los ámbitos de la API de Gmail, nada más. Comienza con nuestra Guía completa de integración de la API de Gmail.
02
¿Cuál es la diferencia entre gmail.readonly y gmail.modify?
Ambos gmail.lectura y gmail.modificar son ámbitos restringidos de la API de Gmail. gmail.lectura proporciona acceso de solo lectura a todos los mensajes, hilos, etiquetas y configuraciones. Tu aplicación no puede enviar ni cambiar nada. gmail.modificar añade la capacidad de leer, redactar, enviar correos electrónicos y administrar etiquetas, pero excluye la eliminación permanente de mensajes. Si tu aplicación necesita leer y enviar, pero no eliminar, gmail.modificar se prefiere a lo más amplio mail.google.com/ alcance. Ver nuestra cómo leer los correos electrónicos de los usuarios a través de una API unificada.
03
¿Necesito una evaluación de seguridad para todos los ámbitos de la API de Gmail?
No. Solo ámbitos restringidos de la API de Gmail requieren una evaluación de seguridad externa anual (aprox. 1 000–4 000 € al año). Ámbitos no confidenciales como gmail.etiquetas requiere solo una revisión estándar de la aplicación OAuth. Ámbitos sensibles como gmail.enviar requiere el proceso de verificación OAuth de Google pero sin evaluación de seguridad. Ámbitos restringidos - incluyendo gmail.lectura, gmail.modificar, gmail.redactar, metadatos de gmail, gmail.insertary mail.google.com/ - requerir el proceso de evaluación completo. Más información al respecto en nuestro Patrones de API de correo electrónico seguro para industrias reguladas.
04
El ámbito gmail.modify se utiliza para modificar correos electrónicos existentes.
En gmail.modificar el alcance otorga acceso de lectura, composición, envío y administración de etiquetas a Gmail, pero excluye la capacidad de eliminar permanentemente los mensajes. Es el alcance restringido recomendado para integraciones de correo electrónico con todas las funciones, como Sincronización de correo electrónico CRM, herramientas de helpdesk y clientes de correo electrónico que necesiten tanto leer como enviar mensajes. Se prefiere sobre mail.google.com/ porque limita la exposición de datos al excluir la funcionalidad de eliminación permanente. Relacionado: enviar correos electrónicos en nombre de los usuarios.
05
Cuántos usuarios de prueba puedo tener antes de completar la verificación del ámbito de la API de Gmail
Puedes probar tu aplicación con hasta 100 cuentas de Google mientras tu aplicación OAuth está en modo de prueba, independientemente de los alcances de la API de Gmail que declares. Estas cuentas de prueba deben agregarse manualmente en la configuración de la pantalla de consentimiento OAuth de la Google Cloud Console. Una vez que superes los 100 usuarios o desees publicar públicamente, deberás completar el proceso de verificación adecuado según tu nivel de sensibilidad del alcance.
06
¿Puedo combinar varios ámbitos de la API de Gmail en una sola solicitud OAuth?
Sí, puedes combinar múltiples ámbitos de la API de Gmail en una sola solicitud de autorización OAuth pasando como un array a alcance parámetro. Por ejemplo, puedes solicitar gmail.enviar + gmail.etiquetas juntos. Sin embargo, combinar ámbitos aumenta los permisos que se muestran en la pantalla de consentimiento de Google y puede activar requisitos de verificación adicionales si algún ámbito combinado está restringido. Solicite siempre la combinación mínima que su aplicación realmente necesite. Para el lado de Microsoft, consulte Ámbitos de OAuth de Microsoft Graph equivalentes.
07
¿Cuál es el alcance de gmail.metadata?
En metadatos de gmail alcance es un alcance restringido de la API de Gmail que otorga acceso a encabezados y etiquetas de correo electrónico, sin ningún acceso al contenido del cuerpo del correo electrónico o a los archivos adjuntos. Resulta útil para motores de enrutamiento, sistemas de categorización o herramientas de análisis que procesan correos electrónicos basándose en el remitente, el destinatario, el asunto o las etiquetas sin leer el contenido privado del mensaje. A pesar de estar restringido, tiene una huella de datos más reducida que gmail.lectura y puede ser más fácil de justificar en una evaluación de seguridad. Profundizamos en nuestra API de sincronización de correo electrónico para sincronización completa de bandeja de entrada.
08
¿Cómo maneja Unipile los ámbitos de la API de Gmail para mi aplicación?
Unipile gestiona los ámbitos de la API de Gmail internamente como parte de su integración de Gmail OAuth alojada. Cuando sus usuarios vinculan sus cuentas de Gmail a través de Unipile, Unipile solicita los ámbitos de OAuth de Gmail apropiados según las funciones que habilite, gestiona el refresco de tokens automáticamente y se encarga de la reautorización cuando los requisitos de los ámbitos cambian. Su equipo no necesita declarar ni gestionar listas de ámbitos de la API de Gmail directamente, y usted se beneficia de Verificación de Google existente de Unipile estado para alcances restringidos. Para obtener más información al respecto, consulta nuestro Comparación de 6 proveedores de API de correo electrónico.
09
¿Qué es gmail.send y cuándo debo usarlo?
En gmail.enviar alcance es una alcance sensible de la API de Gmail que permite que tu aplicación envíe correos electrónicos en nombre de un usuario autenticado, sin conceder acceso de lectura o modificación a los mensajes existentes. Es el ámbito mínimo recomendado para aplicaciones que solo envían correos electrónicos: herramientas de distribución, sistemas de notificación o automatización de seguimiento. Usando gmail.enviar en vez de gmail.modificar evita por completo la evaluación de seguridad de alcance restringido, acelerando significativamente su camino hacia la producción. Vea nuestro Guía de la API dedicada para enviar correos electrónicos.
10
Cómo los ámbitos de la API de Gmail afectan el cumplimiento del RGPD
Los ámbitos de la API de Gmail afectan directamente tu postura de GDPR. principio de minimización de datos te exige solicitar solo los permisos de la API de Gmail necesarios para tu propósito declarado. Tu política de privacidad debe reflejar con precisión a qué datos de Gmail accedes. Solicitar ámbitos excesivos crea una brecha de documentación del RGPD y aumenta la responsabilidad en caso de incumplimiento. Cuando los usuarios revocan la autorización, tu aplicación debe perder inmediatamente el acceso a sus datos de Gmail, esto está reforzado por la invalidación de tokens de Google, pero también debe reflejarse en tus procedimientos de eliminación de datos.

¿Necesitas ayuda para elegir los ámbitos de la API de Gmail adecuados para tu caso de uso? Nuestro equipo puede revisar su arquitectura de integración y recomendar el conjunto de alcance mínimo.

Hable con un experto
es_ESES