# Modulo — Notifiche email **Stato:** implementato e in produzione dal 29/09/2026 (migration `m22`, worker in `mailer/`) **File principali:** `supabase/migrations/20260929120000_m22_notifiche_email.sql`, `mailer/mailer.mjs`, `mailer/mailer-core.ts`, `mailer/healthcheck.mjs`, `mailer/Dockerfile`, `mailer/docker-compose.yml`, `src/lib/preferenze-utente.ts`, `src/routes/profilo.tsx` (interruttore «Email») Questo documento descrive **cosa fa** il canale email. Come si installa, si configura e si diagnostica il worker sta in [WORKER_EMAIL.md](../WORKER_EMAIL.md); le motivazioni delle scelte in [DD-036](../decisions/DD-036.md). ## Obiettivo Far arrivare le notifiche di CrAPP anche per email, all'indirizzo Gmail con cui il giocatore si è registrato, **a costo zero**. È un terzo canale accanto alla push e al centro notifiche in-app ([notifiche.md](notifiche.md)): non li sostituisce e non introduce eventi nuovi. Manda per email **ogni notifica che finisce già in `notifiche_utente`**, di qualunque tipo e per qualunque destinatario. ## Architettura ``` App su Vercel ──scrive──▶ notifiche_utente ──trigger──▶ notifiche_email_coda (Supabase) ▲ polling in uscita │ RPC con service role │ Container Docker sull'host di casa (mailer) │ SMTP 587 (STARTTLS) ▼ smtp.gmail.com ──▶ casella Gmail del giocatore ``` - **Vercel non ospita Docker**, quindi il worker gira su un host proprio e sta **solo in uscita**: interroga Supabase e parla con Gmail. Nessuna porta aperta sul router, nessun IP pubblico, nessun tunnel. - **L'app non invia mai email direttamente.** Continua a scrivere `notifiche_utente` come prima: le route e i cron di M17 non sono stati toccati. Se l'host è spento le mail restano in coda e partono alla ripartenza: consegna in ritardo, mai persa. - **L'accodamento sta nel database** (un trigger), quindi vale per ogni sorgente, cron `pg_cron` compresi. - Il worker gira con **bun** (immagine `oven/bun:1-alpine`, come il resto del progetto) e ha una sola dipendenza, `nodemailer`. Parla con Supabase via `fetch` sulle funzioni RPC di PostgREST, senza `@supabase/supabase-js`. Ha un proprio `package.json` e `bun.lock`, separati da quelli dell'app, che non guadagna nessuna dipendenza. - La chiave con cui il worker si autentica può essere sia una chiave JWT sia una chiave nel formato nuovo `sb_secret_…`: viene inviata in `apikey` e in `Authorization: Bearer` e Supabase accetta entrambe (verificato sul progetto di produzione). ## Quali notifiche e a chi **Ogni riga nuova di `notifiche_utente` genera una mail**: messaggio admin, sollecito presenze, sondaggio pre-partita, compleanno (DD-047: solo il titolo, senza corpo; la mail ha oggetto, link e avviso di disattivazione), presenza modificata (DD-050, ad admin e allenatori). **Fa eccezione il turno palloni** (DD-040, dalla `m26`): per i tipi `turno_palloni`, `turno_palloni_12h`, `_6h`, `_3h` e `turno_palloni_revocato` il trigger non accoda nulla, restano push e centro notifiche. Un tipo nuovo che in futuro finisse in quella tabella viaggerebbe per email senza altro lavoro. Le notifiche già presenti quando si applica la migration **non** vengono inviate: il trigger non ha backfill. Il [catalogo delle notifiche](notifiche.md#catalogo-delle-notifiche) elenca cosa fa partire ciascuna e i suoi canali: tutte le notifiche generate dal server passano da `notifiche_utente` e quindi arrivano anche per email (DD-038). **Chi le riceve:** chi ha la riga in `notifiche_utente`, con la stessa logica delle notifiche in-app. Gli admin non hanno un percorso a parte: ricevono ciò che riceverebbero secondo il proprio slot. L'allenatore riceve solo i messaggi dello staff, non i promemoria degli eventi (DD-039), né il sollecito, il turno palloni e il sondaggio (DD-034, DD-038). Il certificato in scadenza **non genera mail**: non è una notifica ma una card calcolata in Home (DD-035). Se un giorno lo si volesse anche per email sarebbe una sorgente nuova di `notifiche_utente`, da decidere a parte. **Indirizzo:** `giocatori_squadra.email`, la stessa colonna che collega account e giocatore (DD-018). Uno slot senza `auth_user_id` (giocatore non ancora registrato), senza email o il cui account ha spento le email non riceve nulla: la riga in coda passa a `saltata`, senza errore. ## Mittente Il worker invia con un **account Gmail dedicato**, tramite `smtp.gmail.com:587`, autenticandosi con una **password per app**. Come crearla e i problemi noti stanno in [WORKER_EMAIL.md](../WORKER_EMAIL.md#account-gmail-e-password-per-app). Perché Gmail e non un relay come Brevo o Resend: i destinatari sono già su Gmail, quindi la mail parte e arriva dentro la stessa infrastruttura, con SPF e DKIM già a posto e senza comprare né configurare un dominio. Gmail riscrive l'intestazione `From` con l'indirizzo dell'account: il nome visibile è «CrAPP», l'indirizzo no. Il tetto è di circa 500 destinatari al giorno per un account gratuito (valore da verificare); il worker si ferma a `MAIL_LIMITE_GIORNO`. **Non si invia mai direttamente dal proprio IP di casa**: gli IP residenziali sono nelle blocklist e senza reverse DNS le mail finiscono in spam o vengono rifiutate. ## Dati Lo schema completo, con permessi e note, sta in [DATABASE.md](../DATABASE.md); qui il quadro funzionale. **`notifiche_email_coda`** — una riga per notifica da mandare (`notifica_id` è chiave primaria e chiave esterna con `ON DELETE CASCADE`: cancellare la notifica, per esempio con lo swipe, toglie anche la mail non ancora partita). | Colonna | Note | | -------------------- | ----------------------------------------------------------------------- | | `stato` | `in_coda` · `in_invio` · `inviata` · `fallita` · `saltata` | | `tentativi` | invii falliti finora; non cresce per i rinvii «differiti» (vedi sotto) | | `prossimo_tentativo` | il worker prende la riga solo se `<= now()` (backoff) | | `errore` | solo i codici SMTP dell'ultimo errore, mai il testo delle mail | | `inviata_il` | valorizzato a invio riuscito; alimenta il conteggio delle ultime 24 ore | | `aggiornata_il` | serve a riconoscere le righe rimaste `in_invio` per un worker morto | È una tabella a parte e non colonne su `notifiche_utente` perché quella ha una policy `UPDATE` per il giocatore su tutta la riga: un client potrebbe riportare a `in_coda` una mail già partita. La coda ha la RLS attiva **senza alcuna policy** e i permessi tolti a `anon` e `authenticated`: la legge e la scrive solo la service role, cioè il worker. **`preferenze_utente`** — una riga per **account** (`auth_user_id`, non lo slot giocatore), per ora con la sola colonna `email_notifiche` (default `true`). **Nessuna riga significa email attive**: la riga nasce solo quando il giocatore tocca l'interruttore, con un upsert; ognuno legge e scrive solo la propria, per RLS. Non sta su `giocatori_squadra`, che ha una riga per slot e il giocatore può modificare solo in parte (DD-016). **Funzioni RPC** — tutte `SECURITY DEFINER` e con `EXECUTE` solo alla service role: | Funzione | Cosa fa | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `prendi_notifiche_email(p_max)` | Prende fino a `p_max` righe `in_coda` scadute con `FOR UPDATE SKIP LOCKED`, le marca `in_invio` e restituisce indirizzo, oggetto, testo, evento, tipo. | | `esito_notifica_email(id, esito, errore, ora)` | Registra `inviata`, `riprova`, `differita` o `fallita`; agisce solo su righe `in_invio`, così un esito in ritardo non ne sovrascrive uno già deciso. | | `email_inviate_ultime_24h()` | Conta le mail inviate nelle ultime 24 ore, per restare sotto il tetto. | ## Flusso 1. Una sorgente M17 inserisce (o aggiorna con `upsert`) una riga in `notifiche_utente`. 2. Il trigger `notifiche_utente_accoda_email` (`AFTER INSERT OR UPDATE OF creato_il`) la mette in `notifiche_email_coda`. L'`upsert` di turno palloni, sollecito presenze e sondaggio riscrive `creato_il`: è un rinvio voluto e rimette in coda anche la mail. Segnare come letta e l'`ON CONFLICT DO NOTHING` dei cron non toccano quella colonna e non accodano nulla. 3. Ogni `POLL_SECONDI` (30) il worker conta le mail delle ultime 24 ore, ne chiede al massimo quante ne restano sotto il tetto (al più `MAIL_LOTTO`) a `prendi_notifiche_email` e le invia una a una. Prima di prendere il lotto la funzione SQL fa due pulizie: riporta a `in_coda` le righe ferme `in_invio` da più di 10 minuti (worker morto a metà) e segna `saltata` quelle senza destinatario o con le email spente. 4. Ogni invio registra l'esito con `esito_notifica_email`. La preferenza è valutata **al momento dell'invio**, non dell'accodamento: spegnere l'interruttore ferma anche le mail già in coda. ## Affidabilità Il worker classifica l'errore SMTP (`classificaErroreSmtp`): | Tipo | Esempi | Cosa succede | | ---------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `temporaneo` | 4xx, timeout, connessione caduta | Riprova con backoff 1 · 5 · 30 · 120 min; al quinto invio fallito passa a `fallita`. | | `permanente` | 5xx sul destinatario o sul messaggio, indirizzo non valido | `fallita` subito, senza altri tentativi. | | `limite` | `550 5.4.5 Daily user sending quota exceeded` | Tutto il lotto torna in coda tra un'ora **senza consumare tentativi**; il ciclo si ferma. | | `configurazione` | credenziali SMTP rifiutate (535, 534, 530, `EAUTH`) | Come sopra ma tra 15 minuti, e il container **non** risulta più sano (vedi sotto). | Altre situazioni: | Situazione | Comportamento | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Worker fermo o host spento | Le mail restano `in_coda` e partono alla ripartenza. | | Crash tra l'invio e la registrazione | Consegna _almeno una volta_: la riga resta `in_invio`, dopo 10 minuti torna in coda e la mail può arrivare due volte. Mai una perdita. | | Errore nella registrazione dell'esito | Non si tratta come errore SMTP (non parte un secondo invio): il ciclo si interrompe e la riga viene recuperata come sopra. | | Tetto giornaliero raggiunto | Finestra mobile di 24 ore su `inviata_il`, non «fino a mezzanotte»: il worker riprende da solo quando le mail più vecchie escono dalla finestra. | `MAIL_LIMITE_GIORNO` vale 400 di default, sotto i circa 500 di Gmail, per lasciare margine ai messaggi che l'account dedicato potesse mandare per altre vie. **Salute del container.** `mailer.mjs` scrive un timestamp in `/tmp/mailer-ok` a ogni ciclo riuscito; `healthcheck.mjs` (eseguito da Docker ogni minuto, con 30 secondi di tolleranza all'avvio) segnala non sano il container se l'ultimo è più vecchio di 5 minuti. Un ciclo fermato dalle credenziali SMTP rifiutate **non** aggiorna il file, così dopo qualche minuto `docker ps` mostra `unhealthy` invece di far credere che tutto funzioni. Un ciclo fermato dal solo tetto giornaliero è normale e resta sano. ## Contenuto delle mail Sobrio, in testo semplice più una versione HTML minima leggibile da smartphone: oggetto = titolo della notifica (su una riga sola, massimo 200 caratteri), corpo = corpo della notifica, un pulsante «Apri CrAPP» verso `/evento/` quando la notifica riguarda un evento e verso la home altrimenti. In fondo una riga che spiega come disattivare le email (Profilo → Opzioni → Email). Nessuna immagine remota, nessun tracciamento delle aperture. Il testo scritto dall'admin viene sempre escapato nell'HTML. Il `Message-ID` è derivato dall'id della notifica. ## Interfaccia Un solo cambio: in Profilo → Opzioni, sotto «Notifiche», un interruttore **«Email»** (icona busta) che scrive `preferenze_utente` per l'account, con lo stesso stile dell'interruttore «Notifiche» (`useEmailNotifiche()` in `src/lib/preferenze-utente.ts`). Vale per tutti gli slot dell'account. Nessuna schermata nuova. ## Privacy e sicurezza - Le email personali dei giocatori non lasciano Supabase se non verso Gmail. Il worker legge solo l'indirizzo dei destinatari del lotto che sta spedendo, non l'intera rosa. - La service role sta solo sull'host del worker, in un `.env` con permessi `600`; non passa da Vercel. - La password per app si può revocare da Google senza toccare l'account. - I log del worker riportano solo id notifica, tipo ed esito: **mai indirizzi né testi**, e degli errori SMTP solo i codici. Il log del container è limitato a 3 file da 5 MB. - Il canale è **opt-out**: acceso di default, spegnibile dal giocatore. Un interruttore unico, come per la push (nessuna preferenza per tipo). ## Test - **Unit** — [test/unit/mailer-core.test.ts](../../test/unit/mailer-core.test.ts): configurazione, classificazione degli errori SMTP, backoff, tetto giornaliero, composizione della mail (escape, oggetto, link, `Message-ID`), salute, e il ciclo di invio con dipendenze finte (esiti, fermata su tetto e credenziali, registrazione dell'esito che fallisce, log senza dati personali). [test/unit/preferenze-utente.test.ts](../../test/unit/preferenze-utente.test.ts): il default «acceso» senza riga. - **Integrazione** — [test/integration/notifiche-email.test.ts](../../test/integration/notifiche-email.test.ts), sul database locale: trigger su ogni tipo, rinvio da `upsert`, cron che non accoda due volte, cascata alla cancellazione, `prendi_notifiche_email` (destinatario, una sola volta, chiamate concorrenti senza doppioni, slot senza account o senza email, righe orfane recuperate), preferenza (default, spenta, riaccesa, RLS sulle righe altrui), tutti gli esiti, e i permessi (un giocatore o un admin non vedono la coda né chiamano le funzioni del worker). - Nessun test spedisce mail vere: il trasporto SMTP è sostituito da un finto nei test unitari. L'invio reale a Gmail è stato verificato a mano il 29/09/2026 (vedi Limiti noti). ## Limiti noti - Il canale email dipende da un host acceso: non c'è alta disponibilità. - Un 250 da Gmail vuol dire «accettata», non «letta»: non c'è conferma di lettura e non se ne vuole una. - **Le prime mail possono finire in spam.** Verificato il 29/09/2026: la mail di prova, da un account nuovo e senza reputazione, è arrivata ma nella cartella spam. Non dipende dalla configurazione (Gmail accetta e consegna) ma dalla reputazione del mittente. Si migliora segnando i messaggi «Non è spam» e aggiungendo il mittente ai contatti; chi riceve la prima mail va avvisato. Se resta un problema serve un mittente con dominio proprio (vedi Evoluzioni). - Un account collegato a più slot giocatore (`auth_user_id` ripetuto) riceve una mail per slot, dato che `notifiche_utente` ha una riga per `giocatore_id`. - Cambiare l'indirizzo in `giocatori_squadra.email` cambia dove vanno le mail future; le righe già `inviata` non si toccano. - `notifiche_email_coda` non ha pulizia automatica, come `notifiche_utente` (DD-030): le righe spariscono quando la notifica viene eliminata. - L'interruttore «Email» compare solo con il codice che lo contiene: finché una versione più vecchia dell'app è in produzione, le mail partono ma non si possono spegnere dall'app. ## Evoluzioni possibili - Un relay con dominio proprio (Brevo, Resend) se serve un mittente della squadra, se le mail restano in spam o si supera il tetto di Gmail. - Riepilogo settimanale unico al posto di una mail per notifica. - Preferenze per tipo di notifica, nella stessa `preferenze_utente`, insieme a quelle della push. - Rendere il certificato in scadenza una notifica vera (sorgente nuova di `notifiche_utente`).