Vai al contenuto principale

Google - Come configurare l'invio di simulazioni tramite DMI (Direct Message Injection)

  • Aggiornato

Questo articolo descrive come configurare Direct Message Injection (DMI) tramite Google in SMARTFENSE, creando un progetto in Google Cloud, abilitando le API richieste, generando uno o più account di servizio e caricandoli sulla piattaforma. È possibile configurare più account DMI nello stesso progetto e distribuire gli invii tra essi, aumentando la capacità di invio e la resilienza in caso di errori o limiti di quota.

La configurazione di DMI assicura che le email delle simulazioni arrivino nella casella di posta in arrivo degli utenti ed evita che venga mostrato il banner grigio di avviso di Google: "Questo messaggio non è stato inviato in SPAM in base alle impostazioni della tua organizzazione."

Puoi trovare questa guida all'interno della piattaforma SMARTFENSE in Configurazione > Simulazioni > Metodo di invio, selezionando: Direct Message Injection tramite Google.

Prerequisiti

Prima di iniziare la configurazione, assicurati di soddisfare i seguenti requisiti:

  • L'amministratore che esegue la configurazione in Google deve avere il ruolo di superamministratore in Google Workspace.
  • Deve inoltre disporre di un utente amministratore in SMARTFENSE. Questo è necessario perché la validazione della configurazione viene effettuata tramite il pulsante Invia prova a me, e solo gli utenti appartenenti al dominio configurato possono completare con successo tale verifica. L'amministratore riceverà l'email di validazione nella propria casella di posta in arrivo.

Guida alla configurazione di DMI tramite Google

1. Creare un progetto in Google Cloud

  1. Accedi al seguente URL per creare un progetto in Google Cloud: https://console.cloud.google.com/projectcreate
  2. Definisci un nome rappresentativo in "Project Name", ad esempio: SMARTFENSE-DMI.
  3. Una volta creato, verrà mostrata la dashboard del progetto.

2. Abilitare le API richieste

  1. Dal pannello delle API, clicca su "Go to APIs overview".
  2. Clicca su "Enable APIs AND Services".
  3. Cerca e abilita l'API "Gmail API".
  4. Cerca e abilita l'API "Admin SDK API".

3. Creare credenziali e Service Account

  1. Clicca su "APIs & Services > Credentials" nel menu laterale.
  2. Trova il pannello "Service Accounts" e clicca su "Manage service accounts".
  3. Clicca su "Create Service Account".
  4. Compila il modulo con un nome e una descrizione. Per esempio:
    • Nome: SMARTFENSE-DMI
    • Descrizione: Iniezione di messaggi diretti per email di simulazione di SMARTFENSE
  5. Clicca su "Continue".
  6. Clicca su "Done".

4. Generare la Key (JSON) del Service Account

  1. Una volta creato il "Service Account", accedi nuovamente per aggiungere una nuova "Key". Per rientrare, clicca su "APIs & Services > Credentials" nel menu laterale e poi sull'account di servizio creato.
  2. Clicca su "Create new key".
  3. Seleziona l'opzione JSON e crea la "key".
  4. Al termine, verrà scaricato automaticamente un file con estensione ".json". Conserva questo file in modo sicuro.

Avvertenza: il contenuto del file JSON include credenziali sensibili. Limita l'accesso all'amministratore responsabile ed evita di condividerlo tramite canali non sicuri.

5. Configurare la delega in Google Admin

  1. Accedi a admin.google.com
  2. Accedi al menu "Controlli API".                                                   
  3. Clicca su "Gestisci la delega di dominio completo".
  4. Clicca su "Aggiungi nuovo" e completa l'ID cliente con quello corrispondente al "Service Account" creato.                                             
  5. Nei permessi OAuth, copia i seguenti:
    • https://www.googleapis.com/auth/admin.directory.user
    • https://www.googleapis.com/auth/gmail.insert
    • https://www.googleapis.com/auth/gmail.readonly

Importante: SMARTFENSE non utilizza altri permessi oltre a quelli specificati in questa guida.

6. Caricare l'account in SMARTFENSE

  1. Nella piattaforma SMARTFENSE, clicca su "+ Aggiungi account", completa i seguenti campi:
    • Etichetta: inserisci un nome descrittivo per identificare l'account (ad esempio, Account Principale).
    • Service Account Email: l'indirizzo email del "Service Account" creato al punto 3. Creare credenziali e Service Account.
    • JSON Private Key: incolla il contenuto del file JSON scaricato.
    • Assegna un Peso di distribuzione, vedi: Pesi di distribuzione
    • Lascia selezionato: Attivo
  2. Nel campo Destinatario per il test, inserisca un indirizzo email appartenente al dominio configurato nel Service Account. Di default viene utilizzata la propria email. 
  3. Per validare la configurazione, faccia clic su Invia test accanto all'account che desidera validare singolarmente, oppure su Invia test in fondo alla pagina per validare tutti gli account configurati contemporaneamente. Se viene rilevato un errore, verrà mostrata una notifica con i dettagli. 

  4. Una volta che il test ha avuto esito positivo, faccia clic su Salva. Il pulsante rimane disabilitato finché la validazione non viene completata con successo.

Nota: la validazione con Invia prova a me avrà successo solo se l'utente che esegue il test appartiene al dominio configurato nel Service Account.

Configurazione di più account DMI

È possibile aggiungere più account DMI all'interno dello stesso metodo di invio. Questo permette di distribuire gli invii tra gli account configurati e migliorare la capacità e la resilienza dell'invio delle simulazioni.

Non esiste un limite massimo di account configurabili. L'unica restrizione è che deve esserci almeno un account attivo per poter utilizzare DMI; se tutti vengono disattivati, la piattaforma lo segnala al salvataggio della configurazione.

Quanti account conviene configurare?

La raccomandazione si basa su due criteri indipendenti: volume e resilienza.

Per volume

L'API Gmail ha un limite giornaliero di inserimenti per Service Account. Quando questo limite viene raggiunto, la piattaforma mette l'account in cooldown per 60 secondi e ritenta l'invio con altri account disponibili. Se non ci sono altri account disponibili, quei messaggi non vengono consegnati quel giorno.

Il criterio pratico è il numero di utenti che ricevono simulazioni nello stesso giorno:

  • Fino a ~1.000 utenti/giorno: un solo account è sufficiente nella maggior parte dei casi.
  • Tra 1.000 e 3.000 utenti/giorno: conviene avere 2 account, soprattutto se le campagne si concentrano in finestre temporali brevi.
  • Oltre 3.000 utenti/giorno: 3 o più account con peso uniforme per distribuire equamente il carico.

Il segnale più diretto che conviene aggiungere account è aver rilevato errori di quota giornaliera nei log o notare che alcuni utenti non ricevono la simulazione nel giorno previsto.

Per resilienza

Anche se i guasti di autenticazione sono rari, avere almeno 2 account protegge da questo tipo di errore: se le credenziali di un account diventano invalide (ad esempio, chiave JSON scaduta o permessi revocati in Google Admin), l'altro account assorbe tutti gli invii senza interruzioni. Con un solo account configurato, questo tipo di errore blocca l'invio tramite DMI fino alla correzione manuale.

Riassunto della raccomandazione

  • 2 account sono raccomandati per qualsiasi cliente che utilizzi DMI in modo produttivo.
  • 3 o più account sono giustificati per volumi elevati o campagne con finestre di consegna molto ristrette.

Come aggiungere account aggiuntivi

  1. Ripeti i passaggi 3 a 6 (Creare Service Account, generare la Key, configurare la delega in Google Admin e caricare l'account in SMARTFENSE) all'interno dello stesso progetto di Google Cloud per ogni account aggiuntivo.
  2. In SMARTFENSE, accedi alla sezione Account di Direct Message Injection tramite Google e clicca su + Aggiungi account.
  3. Inserisci tutti i dati richiesti: Etichetta, Service Account Email e JSON Private Key. Assegna un peso di distribuzione a ogni account attivo.

Pesi di distribuzione

Il peso di distribuzione definisce la proporzione di invii assegnata a ciascun account. Sono supportati tre schemi principali:

  • Peso uniforme: tutti gli account con peso 1. Distribuisce gli invii in modo equo.
  • Peso proporzionale: se un account ha una quota maggiore o un rendimento migliore, assegnagli un peso maggiore (ad esempio, Account A = 3, Account B = 1).
  • Peso di riserva: assegna peso 1 all'account di riserva e pesi più alti (ad esempio, 3 o 5) agli account principali. Questo riduce la proporzione di invii ricevuti dall'account di riserva senza azzerarla.

Esempio di distribuzione con 3 account:

Account Peso % di invii
Account A 3 50%
Account B 1 17%
Account C 2 33%

Comportamento in caso di errori

Quando un account presenta un errore durante l'invio, SMARTFENSE ritenta automaticamente con un altro account disponibile (fino a 2 ritentativi per messaggio), applicando una redistribuzione intelligente in base al tipo di errore:

  • Limite di invii raggiunto (rate limit o quota giornaliera esaurita): l'account entra in un periodo di attesa di 60 secondi e il messaggio viene ritentato con un altro account.
  • Errore di autenticazione (credenziali invalide): l'account viene escluso per il resto della sessione di invio e il messaggio passa a un altro account.
  • Errore transitorio del server di Google: il messaggio viene ritentato con un altro account senza penalizzare l'account originale.

Questi cooldown e esclusioni si applicano solo durante la sessione di invio in corso, non modificano lo stato dell'account sulla piattaforma né lo segnalano come inattivo.

💡 Best practice

  • Verifica che l'amministratore che esegue la configurazione abbia il ruolo di superamministratore in Google Workspace e utente amministratore in SMARTFENSE prima di iniziare il processo.
  • Utilizzi Invia test su ogni account al momento del caricamento, oppure Invia test in fondo alla pagina per validarli tutti contemporaneamente, prima di salvare la configurazione..
  • Crea tutti gli account aggiuntivi all'interno dello stesso progetto di Google Cloud per semplificare la gestione e l'audit.
  • Conserva ogni file ".json" in un repository sicuro (ad esempio, un gestore di segreti) e definisci un processo interno di accesso per l'amministratore responsabile.
  • Verifica che la delega in "Gestisci la delega di dominio completo" includa esattamente i permessi indicati, per evitare errori di iniezione e ridurre i rischi.
  • Mantieni documentati il Service Account Email e l'Etichetta di ogni account per facilitare audit e supporto tecnico.
  • Se lavori con più account, rivedi periodicamente i pesi di distribuzione per allinearli alla quota disponibile e al comportamento reale di ciascun account.

Articoli correlati