Come ottenere il contenuto originale dell'email in Zoho Desk

Recuperare il contenuto grezzo e originale dell'email per un thread di ticket di Zoho Desk è semplice, una volta che conosci il corretto endpoint API e hai a disposizione gli identificatori giusti.

Perché è importante

Quando un ticket di supporto arriva tramite email, Zoho Desk memorizza sia una versione elaborata sia il payload originale del messaggio. Ci sono situazioni — debug di problemi di codifica, audit delle intestazioni esatte o sviluppo di integrazioni — in cui hai bisogno di quella sorgente non elaborata anziché della vista thread renderizzata. Sapere come chiamare l'endpoint dedicato ti evita di fare scraping dell'interfaccia o di dover indovinare la struttura dei dati.

Procedura passo dopo passo

Passo 1. Raccogli i tuoi identificatori.

Prima di effettuare qualsiasi richiesta, individua due valori: il ticketid del ticket che stai esaminando e il threadid dello specifico thread email all'interno di quel ticket. Entrambi sono disponibili dalla vista dettaglio del ticket in Zoho Desk o da una precedente chiamata API che elenca i thread. ^[1]

Passo 2. Verifica che gli scope OAuth siano configurati.

L'applicazione connessa deve avere come minimo Desk.tickets.READ autorizzato. Senza questo scope, la richiesta verrà rifiutata prima di raggiungere i dati del thread. Controlla la tua configurazione OAuth e assicurati che l'elenco degli scope includa Desk.tickets.READ (e idealmente Desk.tickets.ALL per un accesso più ampio). ^[4]

Passo 3. Assicurati che il tuo client Zoho Desk sia inizializzato con un org ID valido.

L'API di Zoho Desk richiede un'intestazione orgId per ogni chiamata. Se la tua integrazione non ha ancora memorizzato l'ID organizzazione, effettua una chiamata preliminare per recuperare tutte le organizzazioni, prendi il valore id dal primo elemento dell'elenco restituito e salvalo per le richieste successive. ^[3]

Passo 4. Chiama l'endpoint del contenuto originale dell'email.

Invia una richiesta HTTP GET a:

GET /api/v1/tickets/{ticket_id}/threads/{thread_id}/original

Sostituisci {ticketid} e {threadid} con i valori raccolti nel Passo 1. È possibile passare un parametro di query opzionale p per fornire opzioni aggiuntive di paginazione o filtro. ^[1]

In Python, utilizzando un client wrapper, la chiamata si presenta così:

result = desk_api.get_original_mail_content(
    ticket_id="123456",
    thread_id="789012"
)

Il metodo invia una GET al percorso indicato sopra e restituisce il payload grezzo dell'email. ^[1]

Passo 5. Gestisci il rinnovo del token in modo elegante.

I token di accesso scadono. Costruisci la tua integrazione in modo che, quando viene restituito un 401, venga chiamato automaticamente il flusso di rinnovo del token — recuperando un nuovo accesstoken tramite il refreshtoken memorizzato — e venga ripetuta la richiesta originale. Salva il token rinnovato e il suo timestamp di scadenza affinché le chiamate future abbiano successo senza intervento dell'utente. ^[3]

Passo 6. Esamina la risposta.

Il corpo della risposta contiene il contenuto originale dell'email per quel thread. Analizzalo in base al tuo caso d'uso — estraendo intestazioni, parti MIME grezze o il corpo in testo normale secondo le necessità. ^[1]

---

Errori comuni

• Org ID mancante. Zoho Desk rifiuta le richieste prive di un ID organizzazione valido nelle intestazioni della richiesta. Scopri e memorizza sempre l'org ID automaticamente alla prima connessione, anziché presumere che sia già salvato. ^[3]
• Scope insufficienti. Richiedere solo Desk.tickets.WRITE senza Desk.tickets.READ impedirà di recuperare il contenuto del thread. Controlla attentamente la stringa completa degli scope — è facile omettere i permessi di lettura quando ci si concentra sulle operazioni di scrittura. ^[4]
• Thread ID errato. Il thread_id non è uguale al ticket ID. Passare il ticket ID in entrambi i campi è un errore comune; recupera sempre prima l'elenco dei thread per confermare il valore corretto. ^[1]
• Token di accesso scaduti. Se la tua integrazione non implementa un callback di rinnovo del token, le chiamate falliranno silenziosamente dopo la scadenza del token. Implementa la logica di rinnovo descritta nel Passo 5 prima di andare in produzione. ^[3]

---

Cosa verificare

• Verifica che entrambi gli ID siano corretti — conferma che ticketid e threadid corrispondano ciascuno a record reali nel tuo portale Zoho Desk prima di chiamare l'endpoint. ^[1]
• Conferma gli scope OAuth attivi — apri le impostazioni della tua app OAuth e verifica che Desk.tickets.READ (o Desk.tickets.ALL) compaia nell'elenco degli scope autorizzati. ^[4]
• Testa il rinnovo del token end-to-end — fai scadere o revoca deliberatamente un token di accesso in un ambiente di staging e verifica che la tua integrazione esegua correttamente il rinnovo e il nuovo tentativo senza intervento manuale. ^[3]

---

*Beam Help è una risorsa di supporto esperto indipendente per gli utenti Zoho — non siamo il supporto ufficiale Zoho. Per problemi a livello di piattaforma, fai sempre riferimento alla documentazione ufficiale dell'API di Zoho Desk.*