Cómo recuperar la configuración de correo en Zoho

Recuperar la configuración de correo en Zoho CRM y Zoho Desk requiere llamar al endpoint REST adecuado con un token de acceso OAuth válido — la ruta exacta varía según el producto con el que estés trabajando.

Por qué es importante

Al crear integraciones o automatizaciones, a menudo necesitas inspeccionar cómo está configurado el correo saliente o entrante de una organización. Ya sea que estés auditando el enrutamiento de correo en Zoho CRM o listando las configuraciones de buzones de soporte en Zoho Desk, conocer el endpoint correcto y el flujo de autenticación ahorra un tiempo considerable de depuración. Esto es especialmente relevante para equipos que gestionan soporte multicanal o sincronización de correo en CRM. *(Nota: Beam Help es soporte experto independiente para Zoho — no somos el soporte oficial de Zoho.)*

---

Paso a paso

1. Obtener un token de acceso OAuth válido

Antes de llamar a cualquier endpoint de configuración de correo, tu aplicación debe completar el flujo OAuth. Comienza generando una URL de autorización que incluya tu clientid, redirecturi, los scopes configurados, responsetype: code, accesstype: offline y prompt: consent.^[1]

Paso 1a. Dirige al usuario a esa URL de autorización. Tras su aprobación, Zoho redirige de vuelta con un parámetro code.

Paso 1b. Intercambia el código de autorización por tokens enviando un POST a la URL de tokens de Zoho con granttype: authorizationcode, tu clientid, clientsecret, redirecturi y el code recibido. Una respuesta exitosa contiene un accesstoken, un refreshtoken, un apidomain y un valor expires_in.^[1]

Paso 1c. Almacena el timestamp tokenexpiresat (tiempo Unix actual más expiresin) para que tu código sepa cuándo renovar el token. Cuando el token expire, envía un POST a la URL de tokens nuevamente usando granttype: refreshtoken junto con las credenciales de tu cliente para obtener un nuevo accesstoken.^[2]

---

2. Recuperar la configuración de correo en Zoho CRM

Paso 2. Con un token de acceso válido, realiza la siguiente solicitud al endpoint de configuración de CRM:

GET /settings/mail_config

En Python, usando el wrapper interno del cliente, se vería así:

def get_mail_config(self):
    return self.c.request("GET", "/settings/mail_config")

Esta operación (getmailconfig) pertenece a la categoría de ajustes Correo y Social y devuelve la configuración de correo actual de la organización CRM conectada.^[6]

---

3. Listar configuraciones de correo en Zoho Desk

Paso 3. Para Zoho Desk, el endpoint es diferente. Para recuperar las configuraciones de correo a nivel de organización, envía:

GET /api/v1/mailConfigurations

Se puede pasar un parámetro opcional p para paginación o filtrado. En Python:

def list_organizationlevel_mail_configurations(self, p: dict = None):
    return self.c.request("GET", "/api/v1/mailConfigurations", p, None)

Esto lista todas las configuraciones de correo establecidas a nivel de organización dentro de Zoho Desk.^[7]

---

4. Gestionar los errores de autenticación correctamente

Paso 4. Si alguno de los endpoints devuelve un estado HTTP 401, el token de acceso ha expirado o ha sido revocado. En ese caso, solicita al usuario que vuelva a conectar su cuenta de Zoho y reintenta la solicitud tras obtener un token actualizado.^[4]

---

Errores comunes

• Centro de datos (DC) incorrecto. El apidomain devuelto durante el intercambio de tokens refleja el centro de datos del usuario (p. ej., zohoapis.eu para la UE). Utiliza siempre el apidomain de la respuesta del token en lugar de codificar zohoapis.com de forma fija; de lo contrario, las solicitudes fallarán silenciosamente o devolverán errores de autenticación.^[1]
• Scope no incluido. Si los scopes OAuth configurados en el momento de la autorización no cubren el acceso a correo o ajustes, la API rechazará la solicitud. Verifica que tu configuración de ZOHO_SCOPES incluya el scope de correo o ajustes relevante antes de generar la URL de autorización.^[1]
• ID de organización incorrecto. La información de usuario devuelta desde https://accounts.zoho.<DC>/oauth/user/info puede exponer el ID de organización bajo diferentes nombres de campo (orgid, organizationid o ZGID) según el centro de datos. Prueba siempre con varios nombres de campo y gestiona los fallos de forma elegante.^[2]
• Token no renovado antes de su expiración. Comparar el tiempo Unix actual con el valor almacenado en tokenexpiresat antes de cada llamada a la API evita errores 401 innecesarios durante el flujo de trabajo.^[2]

---

Qué verificar

• Confirma la URL base correcta — verifica que las solicitudes se estén enviando al api_domain devuelto durante el intercambio de tokens, no a un dominio codificado de forma fija, para asegurarte de que se apunta al centro de datos correcto.^[1]
• Valida que el token de acceso esté vigente — comprueba que tokenexpiresat sea una fecha futura antes de llamar a /settings/mail_config (CRM) o /api/v1/mailConfigurations (Desk), y renuévalo de forma proactiva si es necesario.^[2]
• Inspecciona el payload de la respuesta — confirma que el JSON devuelto contiene los campos de configuración de correo esperados; un 401 en el cuerpo de la respuesta indica un problema de autenticación que requiere reconexión, no un problema de datos.^[4]