Panoramica dei servizi

Un servizio è un collegamento tra Frontmail e un provider email. Frontmail non invia mai email dalla propria infrastruttura per conto tuo: genera il tuo modello e consegna il messaggio al tuo provider, così recapitabilità, reputazione del mittente e prezzi del provider restano sotto il tuo controllo.

Provider supportati

Provider	Tipo	Ideale per	Webhook di consegna
SMTP (Seznam, Zoho, personalizzato)	`smtp`	Caselle esistenti, server di posta propri	–
Mailgun	`mailgun`	Email transazionali, regione UE o USA	✓
Amazon SES	`ses`	Grandi volumi a basso costo, utenti AWS	✓ (tramite SNS)
Postmark	`postmark`	Consegna transazionale veloce	✓
Mailjet	`mailjet`	Transazionali con sede nell’UE	✓
Brevo	`brevo`	Con sede nell’UE, piano gratuito generoso	✓
Resend	`resend`	API pensata per gli sviluppatori	✓
Gmail (OAuth)	`gmail`	Caselle personali / Google Workspace	–
Outlook / Microsoft 365 (OAuth)	`outlook`	Caselle Outlook.com e Microsoft 365	–

I servizi personali (caselle SMTP, Gmail, Outlook) si configurano in fretta e inviano dalla tua vera casella, ma hanno limiti giornalieri bassi e nessun tracciamento della consegna. I provider transazionali richiedono una configurazione DNS, ma scalano, ti danno gli eventi di consegna, bounce e apertura e offrono una recapitabilità migliore.

Aggiungere un servizio

Proprietari, admin e sviluppatori gestiscono i servizi in Servizi email.

Clicca Aggiungi servizio e scegli il provider.
Per Gmail e Outlook clicca Collega Gmail / Collega Outlook / Microsoft 365 e consenti l’accesso nella finestra del provider. Per gli altri inserisci le credenziali e clicca Verifica e salva: Frontmail le verifica con il provider (senza inviare email) prima di salvarle. Salva senza verificare è disponibile se preferisci controllare più tardi. Le credenziali sono cifrate con AWS KMS (envelope encryption, AES-256-GCM) e non vengono mai più mostrate: puoi solo sostituirle.
Nella pagina del servizio, Prova connessione ripete lo stesso controllo in qualsiasi momento.
Se vuoi, configura l’URL del webhook mostrato nella pagina del servizio (vedi sotto).
Il tuo primo servizio diventa automaticamente quello predefinito; per cambiarlo usa Imposta come predefinito. Lo usano i modelli senza un servizio esplicito e le chiamate API senza service_id. Se elimini un servizio usato da alcuni modelli, questi passano al servizio predefinito.

Mittente predefinito (From)

Ogni servizio può avere un’Email mittente predefinita e un Nome mittente predefinito (nel modulo di aggiunta e nella pagina del servizio, sotto Impostazioni). L’indirizzo mittente di ogni email viene determinato in questo ordine:

Email mittente / Nome mittente nelle impostazioni del modello (possono usare parametri),
l’Email / il Nome mittente predefinito del servizio,
per Gmail e Outlook l’account collegato; per SMTP il nome utente, se è un indirizzo email.

Finché l’email mittente del modello è vuota, l’editor dei modelli mostra quale mittente verrà usato. Cambiare solo il mittente predefinito non ripete il test di connessione. Se nessun passaggio fornisce un indirizzo, gli invii di prova falliscono con sender_not_configured e gli invii reali falliscono in modo definitivo (il credito viene rimborsato).

Servizio di riserva (failover)

Ogni modello ha un servizio principale e un servizio di riserva facoltativo, entrambi scelti nell’editor dei modelli in Impostazioni → Consegna (Servizio e Servizio di riserva). Il sender prova prima il principale. Se fallisce con un errore di autenticazione o definitivo, lo stesso messaggio viene inviato subito tramite il servizio di riserva. La timeline del messaggio mostra un evento failover e la Cronologia mostra quale servizio l’ha effettivamente inviato.

Gli errori temporanei (timeout, throttling, 5xx) non attivano il failover: vengono prima ritentati sul servizio principale, perché di solito si risolvono da soli.

Come vengono gestiti gli errori del provider

Frontmail classifica ogni errore del provider in uno di tre gruppi:

Classe	Esempi	Cosa fa Frontmail
Autenticazione	chiave API non valida o revocata, token OAuth scaduto (Google `invalid_grant`), SMTP `535`	Segna il servizio come unhealthy (Non funziona), scrive al proprietario e agli admin e mostra un banner nella dashboard. Invia tramite il servizio di riserva, se c’è; altrimenti rimborsa il credito e conserva il messaggio come `held_service_error`.
Definitivo	destinatario non valido, mittente o dominio non verificato, messaggio rifiutato dalle policy	Prova il servizio di riserva, se c’è; altrimenti il messaggio diventa `failed` e il credito viene rimborsato. I bounce definitivi (hard bounce) aggiungono l’indirizzo alla lista di soppressione.
Temporaneo	timeout, connessione interrotta, `5xx` del provider, throttling `429`, SMTP `421`/`450`/`451`	Ritenta con backoff esponenziale (rispettando i limiti del provider). Se tutti i tentativi falliscono, il messaggio diventa `failed` e il credito viene rimborsato.

Ogni guida ai provider elenca gli errori più comuni e come vengono classificati.

Messaggi in attesa per un errore del servizio

I messaggi in held_service_error aspettano nella coda dei messaggi in attesa insieme a quelli in attesa per mancanza di crediti, contrassegnati con il motivo servizio. Non appena il servizio torna a funzionare – dopo che hai aggiornato le credenziali, ricollegato OAuth o dopo un controllo di stato riuscito – vengono rilasciati automaticamente: viene riservato di nuovo un credito e partono nell’ordine originale. Puoi anche rilasciarli o scartarli manualmente. Scadono come gli altri messaggi in attesa (Free 3 giorni, piani a pagamento 14 giorni) e ricevi un’email prima che succeda.

Controlli di stato

Ogni giorno: Frontmail verifica ogni servizio (lo stesso controllo di Prova connessione).
Subito dopo un errore di autenticazione durante l’invio.
Al salvataggio: ogni volta che modifichi le credenziali o ricolleghi OAuth.

Un servizio è healthy (Funzionante), unhealthy (Non funziona) o unknown (Non controllato). Quando un servizio smette di funzionare, proprietari e admin ricevono un’email e la dashboard mostra il banner Un servizio email non funziona con il pulsante Sistema il servizio finché non si riprende; ricevi un’altra email quando torna a funzionare e i suoi messaggi in attesa sono stati rilasciati.

Webhook di consegna

I provider transazionali possono comunicare cosa è successo dopo aver accettato il messaggio. Copia l’URL del webhook dalla pagina del servizio (dove trovi anche gli eventi da attivare) nella console del tuo provider:

https://api.frontmail.dev/webhooks/providers/<type>/<token>

<type> è il tipo di provider della tabella sopra (ad es. mailgun), <token> è un token casuale univoco per il servizio: tratta l’intero URL come un segreto. Frontmail verifica anche la firma del provider, dove il provider la supporta.

Gli eventi vengono associati agli stati dei messaggi e alle statistiche:

Evento del provider	Frontmail
delivered	stato `delivered`
hard bounce	stato `bounced` + indirizzo aggiunto alla lista di soppressione
soft bounce	solo evento (il provider ritenta)
reclamo per spam	stato `complained` + indirizzo aggiunto alla lista di soppressione
apertura / clic	eventi `opened` / `clicked` nella timeline e nelle statistiche

Senza webhook, un messaggio si ferma a sent, che significa che il provider l’ha accettato.