Il recupero della configurazione email in Zoho CRM e Zoho Desk richiede di chiamare l'endpoint REST appropriato con un token di accesso OAuth valido — il percorso esatto varia a seconda del prodotto con cui stai lavorando.

Perché è importante

Quando si creano integrazioni o automazioni, spesso è necessario verificare come è configurata la posta in uscita o in entrata per un'organizzazione. Che tu stia controllando il routing email in Zoho CRM o elencando le configurazioni delle caselle di supporto in Zoho Desk, conoscere l'endpoint corretto e il flusso di autenticazione consente di risparmiare molto tempo nel debug. Questo è particolarmente rilevante per i team che gestiscono il supporto multicanale o la sincronizzazione email con il CRM. *(Nota: Beam Help è un servizio di supporto esperto indipendente per Zoho — non siamo il supporto ufficiale Zoho.)*

---

Procedura passo dopo passo

1. Ottenere un token di accesso OAuth valido

Prima di chiamare qualsiasi endpoint di configurazione email, la tua applicazione deve completare il flusso OAuth. Inizia generando un URL di autorizzazione che includa clientid, redirecturi, gli scope configurati, responsetype: code, accesstype: offline e prompt: consent.^[1]

Passaggio 1a. Reindirizza l'utente a quell'URL di autorizzazione. Dopo l'approvazione, Zoho reindirizza con un parametro code.

Passaggio 1b. Scambia il codice di autorizzazione con i token inviando una richiesta POST all'URL del token di Zoho con granttype: authorizationcode, il tuo clientid, clientsecret, redirecturi e il code ricevuto. Una risposta corretta contiene un accesstoken, un refreshtoken, un apidomain e un valore expires_in.^[1]

Passaggio 1c. Memorizza il timestamp tokenexpiresat (tempo Unix corrente più expiresin) in modo che il tuo codice sappia quando aggiornare il token. Quando il token scade, invia nuovamente una richiesta POST all'URL del token usando granttype: refreshtoken insieme alle credenziali del client per ottenere un nuovo accesstoken.^[2]

---

2. Recuperare la configurazione email in Zoho CRM

Passaggio 2. Con un token di accesso valido, invia la seguente richiesta all'endpoint delle impostazioni CRM:

GET /settings/mail_config

In Python, utilizzando il wrapper interno del client, si presenta così:

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

Questa operazione (getmailconfig) rientra nella categoria di impostazioni Mail & Social e restituisce la configurazione email corrente per l'organizzazione CRM connessa.^[6]

---

3. Elencare le configurazioni email in Zoho Desk

Passaggio 3. Per Zoho Desk, l'endpoint è diverso. Per recuperare le configurazioni email a livello di organizzazione, invia:

GET /api/v1/mailConfigurations

È possibile passare un parametro opzionale p per la paginazione o il filtraggio. In Python:

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

Questo elenca tutte le configurazioni email impostate a livello di organizzazione in Zoho Desk.^[7]

---

4. Gestire gli errori di autenticazione in modo appropriato

Passaggio 4. Se uno degli endpoint restituisce uno stato HTTP 401, il token di accesso è scaduto o è stato revocato. In questo caso, chiedi all'utente di riconnettere il proprio account Zoho e riprova la richiesta dopo aver ottenuto un nuovo token.^[4]

---

Errori comuni

Data centre (DC) errato. L'apidomain restituito durante lo scambio del token riflette il data centre dell'utente (ad es., zohoapis.eu per l'UE). Usa sempre l'apidomain dalla risposta del token anziché impostare zohoapis.com come valore fisso, altrimenti le richieste falliranno silenziosamente o restituiranno errori di autenticazione.^[1]
Scope non incluso. Se gli scope OAuth configurati al momento dell'autorizzazione non coprono l'accesso a mail/impostazioni, l'API rifiuterà la richiesta. Verifica che la configurazione ZOHO_SCOPES includa lo scope mail o impostazioni pertinente prima di generare l'URL di autorizzazione.^[1]
Mancata corrispondenza dell'ID organizzazione. Le informazioni utente restituite da https://accounts.zoho.<DC>/oauth/user/info possono esporre l'ID organizzazione con nomi di campo diversi (orgid, organizationid o ZGID) a seconda del data centre. Prova sempre più nomi di campo e gestisci i fallback in modo appropriato.^[2]
Token non aggiornato prima della scadenza. Confrontare il tempo Unix corrente con il valore tokenexpiresat memorizzato prima di ogni chiamata API previene errori 401 non necessari durante il flusso di lavoro.^[2]

---

Cosa verificare

Conferma l'URL base corretto — verifica che le richieste vengano inviate all'api_domain restituito durante lo scambio del token, non a un dominio impostato come valore fisso, per assicurarti di puntare al data centre corretto.^[1]
Verifica che il token di accesso sia aggiornato — controlla che tokenexpiresat sia nel futuro prima di chiamare /settings/mail_config (CRM) o /api/v1/mailConfigurations (Desk), e aggiornalo in modo proattivo se necessario.^[2]
Esamina il payload della risposta — conferma che il JSON restituito contenga i campi di configurazione email attesi; un 401 nel corpo della risposta segnala un problema di autenticazione che richiede la riconnessione, non un problema con i dati.^[4]

Come recuperare la configurazione email in Zoho