Conectar buzones

Cómo funciona la conexión de un buzón

Campbooks lee y envía Gmail y Zoho Mail a través de la API del propio proveedor. Cualquier otro buzón (Yahoo, AOL, iCloud, Fastmail, GMX, WEB.DE, Yandex, un dominio propio) se conecta por IMAP y SMTP con una contraseña de aplicación: consulta Buzones IMAP. Outlook y Microsoft 365 están en camino.

Para Gmail y Zoho no hay nada extra que registrar. El cliente OAuth que configuraste para el Inicio de sesión es el mismo cliente que conecta el buzón. Usa el mismo URI de redirección y el mismo ID de cliente y archivo de secreto. Un proveedor ofrece la conexión de correo en cuanto su cliente está configurado, y no antes.

• Añadir un buzón. En la aplicación, abre Ajustes, luego Buzones, y elige Añadir un buzón. Primero pide la dirección. Una dirección de Gmail o Zoho pasa a la pantalla de consentimiento del proveedor, que pide acceso al correo; cualquier otra dirección recibe el paso de la contraseña de aplicación. Gmail y Zoho solo se ofrecen cuando tu instancia ha configurado su cliente. Pasos para los miembros: Conecta tu buzón.
• Usar también para iniciar sesión. El paso de conectar tiene una casilla, «Usar también esta cuenta para iniciar sesión», marcada por defecto. Desmárcala para un buzón compartido, como support@. Queda conectado, pero nunca se convierte en una forma de iniciar sesión.
• Quién lo ve. Una conexión pertenece al espacio de trabajo y registra quién la conectó. Los propietarios y administradores ven todos los buzones del espacio de trabajo.
• Credenciales. La autorización que Campbooks recibe del proveedor, o la contraseña de un buzón IMAP, se sella con la clave secreta de la instancia. Si pierdes la clave, las conexiones ya no se pueden abrir y cada persona tiene que conectar de nuevo. Consulta La clave secreta de la instancia.
• Desconectar. Desconectar detiene la sincronización y revoca la autorización en el proveedor. Eliges si el correo que ya está en Campbooks se borra (por defecto) o se conserva como historial de solo lectura. El correo en Gmail o en Zoho nunca se toca. Salir del espacio de trabajo, o borrarlo, también revoca las autorizaciones.
• Estado. Cada buzón muestra uno de cuatro estados: Sincronizando, El miembro tiene que volver a conectarla, Ralentizada por el proveedor o Con fallos. Un buzón que necesita volver a conectarse tiene un botón Volver a conectar para quien lo conectó.

Conectar correo requiere el inicio de sesión integrado. Si defines CAMPBOOKS_AUTH__ISSUER con un emisor externo, la conexión de buzones queda desactivada.

Gmail

Funciona con Gmail personal y con cuentas de Google Workspace.

Qué le pide Campbooks a Google

Campbooks pide openid, email y profile para identificar la cuenta, y un ámbito de Gmail:

https://www.googleapis.com/auth/gmail.modify

Ese ámbito lee el correo, cambia etiquetas y envía. No puede borrar correo de forma permanente.

Configurar el proyecto de Google Cloud

1. En la consola de Google Cloud, crea un proyecto o elige el que usas para el inicio de sesión.

2. Abre APIs & Services, luego Library, y activa la Gmail API en ese proyecto. Sin ella, Google rechaza todas las peticiones de correo.

3. Abre OAuth consent screen (en las consolas más recientes, Google Auth Platform). Elige el tipo de usuario:

   • External para cuentas personales de Gmail, o para usuarios de Workspace ajenos a tu organización.
   • Internal si todos los que van a conectar están en tu propia organización de Google Workspace. Una aplicación interna no necesita verificación.

4. Añade los ámbitos openid, email, profile y https://www.googleapis.com/auth/gmail.modify.

5. Define el estado de publicación. Mira la sección siguiente.

6. Abre Credentials, luego Create credentials, luego OAuth client ID. Elige Web application y añade este URI de redirección autorizado:

   https://campbooks.example.com/auth/callback/google

   Usa tu propio CAMPBOOKS_PUBLIC_URL. El URI debe coincidir exactamente, sin barra final.

7. Pon el ID de cliente en .env y el secreto del cliente en deploy/secrets/google-client-secret, y ejecuta docker compose up -d. Los permisos del archivo y las líneas de .env son los de Iniciar sesión con Google, Microsoft o Zoho:

   CAMPBOOKS_GOOGLE__CLIENT_ID=your-client-id
   CAMPBOOKS_GOOGLE__CLIENT_SECRET_FILE=/run/secrets/campbooks/google-client-secret

Testing, publicación y verificación

Google trata gmail.modify como un ámbito restringido. Esto decide quién puede conectar:

• Testing. Solo pueden conectar los usuarios de prueba que indiques, hasta 100. Los refresh tokens duran 7 días, así que todas las conexiones se detienen a la semana y hay que rehacerlas. Usa Testing solo para probar.
• En producción, sin verificar. Cualquiera puede conectar, pero ve la pantalla «Google no ha verificado esta aplicación» y tiene que elegir Avanzado y continuar. Los refresh tokens no caducan a los 7 días. En una instancia personal con pocos usuarios suele ser aceptable. Google también limita las aplicaciones sin verificar a 100 usuarios en total.
• En producción, verificada. Google quita el aviso después de revisar la aplicación. Para un ámbito restringido, Google exige una evaluación de seguridad. Rara vez compensa en una instancia autoalojada.

Para una configuración duradera, publica la aplicación (Publish app en la pantalla de consentimiento) y acepta el aviso.

Cómo sincroniza

Campbooks consulta Gmail periódicamente. No hay configuración de push ni nada que registrar en Google para eso. Tras una sincronización que encontró cambios, la siguiente se ejecuta en el plazo de un minuto. Cuando nada cambia, el intervalo se alarga, hasta cuatro horas. Una conexión nueva lee por defecto los últimos 90 días. Puedes cambiarlo en el Ajuste fino.

Zoho Mail

Qué le pide Campbooks a Zoho

Campbooks pide openid, email y profile, y cuatro ámbitos de Zoho Mail:

Ámbito	Para qué
ZohoMail.accounts.READ	Listar las cuentas de correo del inicio de sesión.
ZohoMail.folders.READ	Leer las carpetas.
ZohoMail.messages.ALL	Leer, cambiar y enviar mensajes.
ZohoMail.tags.ALL	Leer y crear etiquetas, para los flujos.

La pantalla de consentimiento de Zoho es todo o nada. Si falta algún ámbito en la autorización, Campbooks la rechaza y te pide conectar de nuevo.

Configurar la aplicación de Zoho

1. Abre la consola de la API de Zoho de tu región, por ejemplo https://api-console.zoho.eu para Europa. Añade un cliente de tipo Server-based Applications.

2. Activa Multi-DC, para que un solo cliente funcione en todos los centros de datos de Zoho. Sin él, el cliente solo funciona en el centro de datos donde lo creaste.

3. Añade el URI de redirección:

   https://campbooks.example.com/auth/callback/zoho

4. Una aplicación de Zoho de tipo servidor recibe los ámbitos con cada petición, así que no hay nada más que registrar para ellos.

5. Pon el ID de cliente en .env y el secreto del cliente en deploy/secrets/zoho-client-secret, y ejecuta docker compose up -d:

   CAMPBOOKS_ZOHO__CLIENT_ID=your-client-id
   CAMPBOOKS_ZOHO__CLIENT_SECRET_FILE=/run/secrets/campbooks/zoho-client-secret

Centros de datos

Zoho guarda cada cuenta en un centro de datos, y Campbooks lee el correo desde ahí. Se aceptan estos servidores de cuentas:

Región	Servidor de cuentas
Estados Unidos	https://accounts.zoho.com (por defecto)
Europa	https://accounts.zoho.eu
India	https://accounts.zoho.in
Australia	https://accounts.zoho.com.au
Japón	https://accounts.zoho.jp
Canadá	https://accounts.zoho.ca
Arabia Saudí	https://accounts.zoho.sa
Reino Unido	https://accounts.zoho.uk

Con Multi-DC activado, deja CAMPBOOKS_ZOHO__ACCOUNTS_SERVER sin definir. Sin Multi-DC, defínelo con el servidor de cuentas del centro de datos donde registraste el cliente:

CAMPBOOKS_ZOHO__ACCOUNTS_SERVER=https://accounts.zoho.eu

Varias cuentas de correo en un solo inicio de sesión

Un inicio de sesión de Zoho puede tener varias cuentas de correo. Cada cuenta de correo se convierte en su propia bandeja de entrada en Campbooks. Una persona puede conectar más de un inicio de sesión de Zoho.

Cuando alguien se registra con Zoho, Zoho pide por segunda vez acceso al correo, y solo si la cuenta es nueva. Iniciar sesión de nuevo nunca lo pide.

Volver a conectar una vez, para las etiquetas

Las conexiones de Zoho hechas antes de añadir el ámbito de etiquetas siguen sincronizando, pero sin etiquetas ni flujos. Para tenerlos, vuelve a conectar el buzón una vez desde Ajustes, luego Buzones. Campbooks pasa entonces a añadir etiquetas Campbooks/<Flujo> en Zoho para los flujos para los que Zoho no tiene un lugar propio.

Cómo sincroniza

Campbooks consulta Zoho periódicamente, porque Zoho no tiene push. Zoho tampoco tiene registro de cambios, así que Campbooks además vuelve a leer toda la ventana de cada buzón cada 6 horas por defecto. Respeta 60 peticiones por minuto por cada inicio de sesión de Zoho. Cámbialo en el Ajuste fino.

Ajuste fino

Todo esto es opcional, y los valores por defecto sirven para la mayoría de las instancias. Añádelos a .env y ejecuta docker compose up -d. También están en Configuración.

Variable	Valor por defecto	Qué hace
CAMPBOOKS_CONNECTORS__GMAIL__BACKFILL_DAYS	90	Hasta dónde lee una conexión nueva de Gmail. De 1 a 3650.
CAMPBOOKS_CONNECTORS__POLL__MIN_SECONDS	60	Intervalo tras una sincronización que encontró cambios.
CAMPBOOKS_CONNECTORS__POLL__MAX_SECONDS	14400	Intervalo más largo de un buzón inactivo.
CAMPBOOKS_CONNECTORS__ZOHO__BACKFILL_DAYS	90	Hasta dónde lee un buzón nuevo de Zoho. De 1 a 3650.
CAMPBOOKS_CONNECTORS__ZOHO__REQUESTS_PER_MINUTE	60	Peticiones que cada inicio de sesión de Zoho puede hacer por minuto.
CAMPBOOKS_CONNECTORS__ZOHO__SWEEP_MINUTES	360	Minutos entre relecturas completas de la ventana de un buzón de Zoho.

Los límites de tamaño, el presupuesto de cuota de Google y los umbrales de fallo están en Configuración.

Solución de problemas

Qué ves	Causa y solución
Google: Error 400: redirect_uri_mismatch	El URI de redirección del cliente de Google no es exactamente ${CAMPBOOKS_PUBLIC_URL}/auth/callback/google. Revisa el https://, el host y que no haya barra final.
Google: access_denied, o «This app is blocked» o «has not completed the Google verification process»	La aplicación está en Testing y la persona no es un usuario de prueba. Añádela a los usuarios de prueba de la pantalla de consentimiento, o publica la aplicación.
Google: la sincronización falla con 403 accessNotConfigured, o «Gmail API has not been used in project»	La Gmail API no está activada en el proyecto al que pertenece el cliente. Actívala en APIs & Services, luego Library, y espera unos minutos.
Google: las conexiones se detienen a los 7 días aproximadamente	La aplicación está en Testing, que limita los refresh tokens a 7 días. Publica la aplicación y vuelve a conectar cada buzón.
Zoho: invalid_client	El cliente se registró en otro centro de datos. Activa Multi-DC, o define CAMPBOOKS_ZOHO__ACCOUNTS_SERVER con el servidor de cuentas del centro de datos donde creaste el cliente.
Zoho: un error de redirección en la pantalla de consentimiento	El URI de redirección del cliente de Zoho no es exactamente ${CAMPBOOKS_PUBLIC_URL}/auth/callback/zoho.
«Campbooks no ha recibido acceso a lo que elegiste»	La persona dejó fuera un permiso en la pantalla de consentimiento. Conecta de nuevo y permite todo.
«El miembro tiene que volver a conectarla» en un buzón	El proveedor revocó la autorización o esta caducó. Quien lo conectó elige Volver a conectar (o pulsa R) en Ajustes, luego Buzones.
«Campbooks no reconoce el centro de datos de Zoho de esta cuenta»	La cuenta está en un centro de datos que no figura en la lista de arriba.
El proveedor no se ofrece en Conectar	Falta el ID de cliente o el secreto, o no se reinició el servidor. Revisa docker compose logs server.

Otros buzones

Cualquier otro buzón se conecta por IMAP y SMTP con una contraseña de aplicación. Viene activado por defecto y solo necesita la clave secreta de la instancia. Consulta Buzones IMAP. El correo de Outlook o Microsoft 365 está en camino.