Gmail (OAuth)

L’integrazione Gmail invia i modelli Frontmail dalla tua casella Gmail o Google Workspace tramite la Gmail API. I messaggi inviati compaiono nella cartella Posta inviata, le risposte tornano nella tua casella e i destinatari vedono una normale email da parte tua.

Scegli Gmail quando hai un sito personale, un portfolio o una piccola attività e vuoi che gli invii dei moduli e le notifiche partano dall’indirizzo che usi già, senza configurare il DNS se usi @gmail.com. Non è pensato per i volumi: Google limita l’invio giornaliero (vedi Limiti) e non ci sono webhook di consegna. Per volumi transazionali usa Mailgun, Postmark, Amazon SES o Resend. Vedi la panoramica dei servizi.

OAuth invece delle password per le app

Puoi collegare Gmail anche tramite SMTP con una password per le app, ma OAuth è più sicuro: Frontmail non vede mai la tua password, il permesso è limitato all’invio e puoi revocarlo in qualsiasi momento dal tuo Account Google.

Prerequisiti

• Un account Gmail (@gmail.com) o un utente Google Workspace con Gmail attivo.
• Per Workspace: l’amministratore deve consentire alle app di terze parti di accedere ai dati Google oppure considerare esplicitamente attendibile Frontmail in Console di amministrazione → Sicurezza → Accesso e controllo dei dati → Controlli API → Controllo dell’accesso alle app.
• Nient’altro: nessuna chiave API, nessun progetto Google Cloud.

Collegamento in Frontmail

1. Apri Servizi email → Aggiungi servizio → Gmail.
2. Clicca Collega Gmail. Verrai reindirizzato a Google.
3. Scegli l’account e controlla la schermata di consenso. Frontmail richiede:
   • https://www.googleapis.com/auth/gmail.send – inviare email per tuo conto. È uno scope di solo invio: Frontmail non può leggere, cercare, eliminare o modificare alcuna email nella tua casella.
   • openid email – il tuo indirizzo email, così la dashboard può mostrare quale account è collegato e usarlo come indirizzo mittente predefinito.
4. Clicca Consenti. Google ti riporta indietro e il servizio viene salvato, con l’indirizzo collegato in evidenza.
5. Se vuoi, imposta Max email al secondo (predefinito 2/s) e clicca Prova connessione, che aggiorna l’access token e verifica che il permesso gmail.send sia stato concesso.

Cosa viene salvato: Frontmail salva il refresh token OAuth (e un access token di breve durata), cifrati con AWS KMS (envelope encryption). L’access token scade dopo circa un’ora; Frontmail lo rinnova in modo trasparente prima dell’invio. Il flusso usa PKCE e richiede sempre l’accesso offline, quindi un nuovo collegamento genera un refresh token nuovo.

Verifica dell’app

L’app OAuth di produzione di Frontmail è verificata da Google per lo scope gmail.send, quindi vedi il nome di Frontmail e nessun avviso di «app non verificata».

Quando il token smette di funzionare

Google invalida un refresh token quando:

• revochi l’accesso in Account Google → Sicurezza → App e servizi di terze parti → Frontmail,
• cambi la password dell’account Google (per gli scope Gmail Google revoca i token esistenti),
• non usi il token per 6 mesi,
• oppure un amministratore Workspace rimuove l’accesso dell’app.

L’invio o il controllo di stato successivo fallisce allora con invalid_grant. Frontmail lo tratta come un errore auth: il servizio viene segnato come unhealthy, ricevi un’email e un banner nella dashboard, e i messaggi restano in attesa (o vengono inviati tramite il servizio di riserva) finché non clicchi Ricollega nella pagina del servizio. Il nuovo collegamento crea un nuovo refresh token e rilascia automaticamente i messaggi in attesa.

App OAuth self-hosted / in «Test»

Se usi Frontmail con il tuo client OAuth Google Cloud il cui stato di pubblicazione è Testing, Google fa scadere i refresh token dopo 7 giorni: il servizio diventerà unhealthy ogni settimana. Pubblica l’app (e completa la verifica per lo scope sensibile gmail.send) per avere token duraturi. Questo non vale per l’app ospitata su frontmail.dev.

DNS: SPF, DKIM e DMARC

• Indirizzi @gmail.com: non c’è niente da fare, Google firma e autentica la posta.
• Google Workspace sul tuo dominio: pubblica i record di Google, se non l’hai già fatto:

; SPF
example.com.                    TXT  "v=spf1 include:_spf.google.com ~all"

; DKIM – da generare in Console di amministrazione → App → Google Workspace → Gmail → Autentica email
google._domainkey.example.com.  TXT  "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A…"

; DMARC
_dmarc.example.com.             TXT  "v=DMARC1; p=none; rua=mailto:dmarc@example.com"

Dopo aver pubblicato il record DKIM, clicca Avvia autenticazione nella Console di amministrazione. Rendi DMARC più restrittivo (p=quarantine / p=reject) quando i report sono puliti.

Nota

I requisiti 2024 di Google per i mittenti massivi valgono per la posta inviata verso utenti Gmail da qualsiasi provenienza, Workspace compreso. Un modulo di contatto non raggiungerà la soglia di 5.000 al giorno, ma SPF + DKIM + DMARC sul tuo dominio Workspace sono comunque consigliati.

Indirizzo mittente: Gmail invia come l’account collegato. Puoi usare un altro indirizzo solo se è configurato come alias Invia messaggio come nelle impostazioni di Gmail; altrimenti Gmail riscrive il mittente con l’indirizzo dell’account.

Regioni

Non ci sono regioni: la Gmail API è globale.

Limiti di invio

Google applica limiti giornalieri per utente. Superarli blocca l’invio fino a 24 ore.

Account	Limite approssimativo
Gmail personale (@gmail.com)	~500 destinatari al giorno
Google Workspace	~2.000 messaggi al giorno (meno durante la prova)
Gmail API	250 unità di quota per utente al secondo; un invio = 100 unità

Per questo Frontmail invia al massimo 2 messaggi al secondo tramite Gmail. Quando Google risponde dailyLimitExceeded, Frontmail aspetta un’ora tra un tentativo e l’altro; se il limite persiste, il messaggio finisce come failed e il credito viene rimborsato.

Tracciamento della consegna (webhook)

Gmail non ha webhook di consegna, quindi non c’è niente da configurare e nessun URL del webhook nella pagina del servizio. Frontmail sa solo se Google ha accettato il messaggio (sent) o l’ha rifiutato (failed). I bounce arrivano come normali email «Delivery Status Notification» nella tua casella Gmail e non vengono aggiunti automaticamente alla lista di soppressione di Frontmail. Aperture e clic non vengono tracciati.

Errori comuni

• auth – il servizio non funziona (token revocato/scaduto, invalid_grant, 401/403, Gmail non attivo per l’utente Workspace). Il servizio viene segnato come unhealthy; il proprietario riceve un’email e un banner nella dashboard. Subentra il servizio di riserva del modello, se c’è; altrimenti il credito viene rimborsato e il messaggio aspetta nella coda dei messaggi in attesa come held_service_error e viene inviato automaticamente dopo il nuovo collegamento (ricontrollato al salvataggio e dal controllo di stato giornaliero).
• permanent – questo messaggio non può essere inviato (destinatario non valido, messaggio troppo grande, validazione 400). Servizio di riserva se configurato, altrimenti failed e rimborsato.
• transient – 5xx, limiti di frequenza/giornalieri, timeout. Ritentato con backoff esponenziale; dopo l’ultimo tentativo failed e rimborsato.

Risposta di Google	Classe	Cosa fare
invalid_grant – Token has been expired or revoked	auth	Clicca Ricollega nella pagina del servizio e concedi di nuovo l’accesso.
401 – Invalid Credentials	auth	Di solito si risolve con il rinnovo automatico del token; se persiste, ricollega.
403 – Insufficient Permission / insufficient_scope	auth	Nella schermata di consenso è stata tolta la spunta a gmail.send: ricollega e consenti l’invio.
403 – accesso bloccato dall’amministratore Workspace	auth	Chiedi all’amministratore di considerare attendibile Frontmail in Controlli API.
400 failedPrecondition – Mail service not enabled	auth	L’utente Workspace non ha una licenza Gmail; attiva Gmail o collega un altro account.
400 invalidArgument – Invalid To header	permanent	Vedi destinatario non valido.
413 / 400 – messaggio troppo grande	permanent	Riduci la dimensione degli allegati (il limite di Gmail è 25 MB).
429 / 403 rateLimitExceeded, userRateLimitExceeded, dailyLimitExceeded	transient	Rallenta o aspetta che il limite giornaliero si azzeri; valuta un provider transazionale.
500 / 503 backendError	transient	Disservizio di Google: Frontmail ritenta.

Checklist

• Collegato con Collega Gmail; consenso concesso per l’invio di email
• Workspace: Frontmail consentito nei Controlli API (se limitati)
• Workspace sul proprio dominio: SPF include:_spf.google.com, DKIM google._domainkey, DMARC
• Mittente del modello = l’indirizzo collegato o un alias Invia messaggio come configurato
• Prova connessione va a buon fine
• Volume giornaliero ben al di sotto dei limiti di Google
• Servizio di riserva configurato sui modelli importanti, nel caso il token venga revocato