Perché l’assistente possa leggere la posta in Google Workspace e creare lì le bozze, gli serve l’accesso tramite la Gmail API. Ci sono due strade ed entrambe si basano su ciò che l’organizzazione crea nel proprio Google Cloud. draften non ha un’app comune a cui basta dare il consenso. Vale per il nostro servizio come per un’installazione sul tuo server.
Supportiamo Google Workspace. Gli account personali @gmail.com non sono supportati: non si può accedere a draften con essi e collegarli richiederebbe che l’app venisse verificata da Google.
Quale strada scegliere
| Per tutta l’organizzazione | Con l’account della casella | |
|---|---|---|
| In draften | una registrazione (account di servizio) in Organizzazione → Integrazioni | il pulsante Collega Gmail accanto alla casella |
| In Google | un account di servizio con una chiave e la domain-wide delegation | un client OAuth e una schermata di consenso di tipo Internal |
| Chi lo crea | un amministratore di Google Cloud e un super amministratore di Google Admin | un amministratore di Google Cloud |
| Chi deve accedere | nessuno | il proprietario di ogni casella, una volta |
| Quali caselle raggiunge | tutte le caselle del dominio | solo la casella con il cui account si è effettuato l’accesso |
| Accesso a draften con l’account Google | no, è una cosa separata | lo stesso client OAuth serve anche per l’accesso |
Per un’organizzazione con più caselle la strada più semplice è quella per tutta l’organizzazione. Con l’account della casella conviene quando non vuoi dare a una sola chiave l’accesso a tutte le caselle del dominio, o quando introduci comunque l’accesso con l’account Google.
Puoi avere entrambe le strade insieme; ogni casella ne usa una. draften chiede solo l’ambito gmail.modify – lettura e creazione di bozze, non invia nulla.
Strada A: per tutta l’organizzazione
In Google Cloud
Lavori in https://console.cloud.google.com, nell’organizzazione del tuo dominio Workspace.
- Scegli un progetto, o creane uno nuovo (per esempio
draften). - APIs & Services → Library → Gmail API → Enable.
- IAM & Admin → Service accounts → Create service account. Un nome, per esempio
draften-posta. Non gli servono ruoli nel progetto – l’accesso alla posta glielo dà solo la delega in Google Admin. Fai clic su Done. - Apri l’account di servizio e annota il suo Unique ID – il Client ID numerico.
- Scheda Keys → Add key → Create new key → JSON → Create. Viene scaricato un file con la chiave.
Se Google rifiuta di creare la chiave, la tua organizzazione ha attiva la policy iam.disableServiceAccountKeyCreation (le nuove organizzazioni la hanno per impostazione predefinita). Per questo progetto la disattiva un amministratore dell’organizzazione in IAM & Admin → Organization policies.
In Google Admin
Ti serve un super amministratore. In https://admin.google.com apri Security → Access and data control → API controls → Manage Domain Wide Delegation → Add new. Client ID: l’ID numerico del passo 4. OAuth scopes: https://www.googleapis.com/auth/gmail.modify. Fai clic su Authorize. Di solito la delega entra in vigore in pochi minuti, in rari casi dopo diverse ore.
In draften
- Apri Organizzazione → Integrazioni, il riquadro Accesso alla posta per tutta l’organizzazione. Le registrazioni le gestiscono il proprietario o un gestore dell’organizzazione.
- Sistema: Google Workspace. Compila Nome, in Chiave dell’account di servizio (JSON) scegli il file scaricato e fai clic su Aggiungi registrazione. La chiave viene salvata cifrata; nel riquadro si vedono poi solo l’email dell’account di servizio e il suo Client ID.
- Nella pagina di ogni casella, nel riquadro Accesso alla posta, scegli in Usa questa registrazione, fai clic su Applica e poi su Testa la connessione. La procedura con le schermate la mostra la guida Aggiungere e collegare una casella.
Poi elimina il file della chiave scaricato. Chi lo ha entra in ogni casella del dominio. Una nuova chiave dello stesso account di servizio la carichi nella registrazione con nuova chiave (JSON); la chiave di un altro account di servizio aggiungila come nuova registrazione. Elimina la vecchia chiave in Google Cloud.
Con la casella automatica attiva (Come accedono i membri) una nuova casella si lega da sola alla registrazione, quando per Google Workspace ce n’è esattamente una attiva.
Strada B: con l’account della casella (Collega Gmail)
Qui il proprietario della casella accede con il suo account Google e concede l’accesso solo alla propria posta. Lo stesso client OAuth serve anche per l’accesso a draften con l’account Google.
In Google Cloud
- In draften apri prima Organizzazione → Come accedono i membri, il riquadro Accesso con account e collegamento delle caselle. Mostra due Redirect URI esatti per il tuo indirizzo di draften – terminano con
/auth/google/callbacke/mailboxes/connect/google/callback. Copiali da lì; devono corrispondere carattere per carattere. - Nel progetto con la Gmail API attivata (passo 2 della strada A) apri APIs & Services → OAuth consent screen. User type: Internal – potrà accedere solo un account del tuo dominio e l’app non deve essere verificata da Google. Compila il nome dell’app (per esempio
draften) e un’email di contatto. - Nella parte degli ambiti (Scopes / Data access) aggiungi
openid,email,profileehttps://www.googleapis.com/auth/gmail.modify. - APIs & Services → Credentials → Create credentials → OAuth client ID. Application type: Web application. In Authorized redirect URIs inserisci entrambi gli indirizzi del riquadro e fai clic su Create.
- Copia il Client ID e il Client secret.
In draften
- Il proprietario dell’organizzazione, nel riquadro Accesso con account e collegamento delle caselle, compila in Client OAuth di Google i valori Client ID e Client secret e fa clic su Salva.
- Il proprietario della casella apre la pagina della casella e nel riquadro Accesso alla posta fa clic su Collega Gmail. Accede con l’account di quella casella – draften rifiuta un altro account – e concede l’accesso. Il pulsante lo vede solo il proprietario della casella, e solo se l’organizzazione ha il client OAuth.
- Poi Testa la connessione.
L’accesso con l’account Google lo attivi nella stessa pagina: in Domini email dell’organizzazione scrivi il tuo dominio Workspace – quello principale, non un alias (quello Google non lo invia all’accesso). Appena l’organizzazione ha sia il client OAuth sia il dominio, i membri accedono con l’account Google e le loro password smettono di funzionare – vedi Come accedono i membri.
Quando la casella si scollega
- L’account è stato eliminato o bloccato, o l’accesso è stato revocato – Google smette di rilasciare token e draften scollega la casella. Collegala di nuovo (Ricollega Gmail), oppure con la strada A.
- “Il fornitore non ha rilasciato un refresh token” – il proprietario della casella rimuove l’app nelle impostazioni del suo account Google (Sicurezza → App e servizi di terze parti) e collega di nuovo la casella.
- “Ha effettuato l’accesso un account diverso dall’indirizzo della casella” – durante il collegamento scegli l’account proprio di quella casella.
Errori del test della connessione
Il test verifica tre passaggi: Accesso, Token e autorizzazione e Lettura della Posta in arrivo.
| Nel messaggio | Che cosa significa | Che cosa fare |
|---|---|---|
la delega per l’ambito non è consentita (unauthorized_client) | in Google Admin manca la domain-wide delegation, o ha un altro Client ID o ambito | controllare la delega in Google Admin: l’ID numerico e l’ambito esatto gmail.modify |
invalid_grant con l’account di servizio | questa casella non esiste nel dominio Workspace | controllare l’indirizzo della casella |
| “Gmail API has not been used…” | nel progetto la Gmail API non è attivata | attivare la Gmail API (passo 2) |
token senza gmail.modify | la delega o la schermata di consenso non ha l’ambito gmail.modify | aggiungere l’ambito |
invalid_grant, deleted_client con un account collegato | il collegamento è stato revocato o il client OAuth eliminato | Ricollega Gmail |
Altri errori li descrive Risoluzione dei problemi.