Mailgun

Mailgun è un servizio di email transazionali pensato per gli sviluppatori. È una scelta predefinita solida per Frontmail: un’API semplice, regioni USA e UE, dati dettagliati sugli eventi e webhook per consegne, bounce, reclami, aperture e clic.

Scegli Mailgun quando invii posta transazionale (registrazioni, ricevute, notifiche, invii di moduli) dal tuo dominio, vuoi tracciare bounce e reclami e preferisci tenere i dati nell’UE (regione UE di Mailgun). Per qualche email da una casella personale, SMTP o Gmail sono più semplici. Per un confronto vedi la panoramica dei servizi.

Prerequisiti

Un account Mailgun. I nuovi account partono con un dominio sandbox che può inviare solo a destinatari autorizzati (vedi Sandbox e limiti).
Un dominio di invio aggiunto e verificato in Mailgun: consigliamo un sottodominio come mg.example.com, così la reputazione e il DNS del dominio principale restano separati.
Una chiave API. Crea una chiave dedicata a Frontmail in Account settings → API security → Add new key (interfaccia precedente: Account → API keys).
- Usa una chiave con il ruolo più restrittivo che possa ancora inviare e leggere le informazioni del dominio (ad es. Developer invece di Admin).
- Una domain sending key (Sending → Domain settings → Sending API keys) può inviare, ma non leggere il dominio, quindi Prova connessione e il controllo di stato giornaliero la segnaleranno come non funzionante. Usa una chiave privata dell’account.
Facoltativo: la HTTP webhook signing key da Sending → Webhooks per gli eventi di consegna.

Collegamento in Frontmail

Apri Servizi email → Aggiungi servizio → Mailgun.
Compila i campi:

Campo	Dove trovarlo	Esempio
Regione	La regione mostrata accanto al dominio in Mailgun (Sending → Domains)	`UE (api.eu.mailgun.net)`
Dominio di invio	Sending → Domains, esattamente come è elencato	`mg.example.com`
Chiave API	Account settings → API security (mostrata una sola volta alla creazione)	`key-3ax6…` / `a1b2c3…-us`
Chiave di firma dei webhook	Sending → Webhooks → HTTP webhook signing key	`8c1f…`
Max email al secondo	Facoltativo; predefinito 10/s	`5`

Clicca Verifica e salva: Frontmail chiama l’API di Mailgun per il dominio e verifica che chiave, regione e dominio corrispondano.
Il servizio viene salvato quando il controllo va a buon fine. Le credenziali sono cifrate con AWS KMS (envelope encryption); solo il processo di invio le decifra al momento dell’invio.

L’indirizzo mittente del modello deve essere sul dominio di invio (ad es. hello@mg.example.com), oppure sul dominio principale se hai verificato quello.

DNS: SPF, DKIM e DMARC

Mailgun mostra i record esatti per il tuo dominio in Sending → Domains → DNS records. Per mg.example.com hanno questo aspetto:

; SPF
mg.example.com.                     TXT    "v=spf1 include:mailgun.org ~all"

; DKIM – il selettore viene generato per ogni dominio (ad es. pic, k1, smtp, mx)
pic._domainkey.mg.example.com.      TXT    "k=rsa; p=MIGfMA0GCSqGSIb3DQEB…"

; Ricezione / gestione dei bounce (consigliato)
mg.example.com.                     MX 10  mxa.mailgun.org.
mg.example.com.                     MX 10  mxb.mailgun.org.     ; UE: mxa.eu.mailgun.org / mxb.eu.mailgun.org

; Tracciamento di aperture e clic
email.mg.example.com.               CNAME  mailgun.org.         ; UE: eu.mailgun.org

; DMARC – sul dominio organizzativo, inizia con il monitoraggio
_dmarc.example.com.                 TXT    "v=DMARC1; p=none; rua=mailto:dmarc@example.com"

Copia il selettore DKIM da Mailgun, non da questo esempio: cambia da dominio a dominio (pic._domainkey, k1._domainkey, …). I domini più recenti possono usare anche il DKIM delegato tramite CNAME con rotazione automatica delle chiavi.
Se il dominio principale ha già un SPF per la tua casella, va bene così: il sottodominio ha il suo record SPF.
Clicca Verify DNS settings in Mailgun; la propagazione può richiedere da pochi minuti ad alcune ore.
Quando i report DMARC sono puliti, passa a p=quarantine e più avanti a p=reject.

Regioni

Mailgun gestisce due regioni completamente separate:

Regione	Host API	Quando usarla
USA	`api.mailgun.net`	il dominio è stato creato nella regione USA (predefinita)
UE	`api.eu.mailgun.net`	il dominio è stato creato nella regione UE (i dati restano nell’UE)

Un dominio esiste in una sola regione, quindi scegli la regione in cui è stato creato il dominio. Una mancata corrispondenza restituisce 404 Domain not found, che Frontmail tratta come errore di autenticazione. La regione non si può cambiare in seguito: per spostarti, aggiungi di nuovo il dominio nell’altra regione.

Sandbox e limiti

Dominio sandbox (sandbox123….mailgun.org): invia solo a destinatari autorizzati (fino a 5) che hanno confermato un’email di invito. Tutto il resto fallisce con “Free accounts are for test purposes only”. Va bene per una prima prova, non per la produzione.
Piano gratuito: circa 100 email al giorno.
Account / domini nuovi possono essere limitati da Mailgun finché non costruisci una storia di invio o non completi la verifica aziendale.
La frequenza predefinita di Frontmail per Mailgun è di 10 messaggi al secondo per servizio; abbassala in Max email al secondo se Mailgun ti rallenta.

Webhook (tracciamento della consegna)

Mailgun può comunicare cosa è successo dopo aver accettato un messaggio.

Copia l’URL del webhook dalla pagina del servizio in Frontmail (pulsante di copia accanto a URL del webhook). Ha questo aspetto:
```
https://api.frontmail.dev/webhooks/providers/mailgun/<token>
```
<token> è univoco per questo servizio: non condividerlo tra servizi.
In Mailgun apri Sending → Webhooks, scegli il dominio (e la regione) giusti e aggiungi l’URL per questi eventi:

Evento Mailgun	Evento Frontmail
Delivered	`delivered`
Permanent failure	`bounced` – l’indirizzo viene aggiunto alla lista di soppressione
Temporary failure	registrato sul messaggio; Mailgun continua a ritentare
Spam complaints	`complained` – aggiunto alla lista di soppressione
Opens	`opened` (richiede il tracciamento delle aperture sul dominio)
Clicks	`clicked` (richiede il tracciamento dei clic sul dominio)

Copia la HTTP webhook signing key dalla stessa pagina nel campo Chiave di firma dei webhook del servizio in Frontmail.

Verifica della firma: ogni webhook di Mailgun contiene timestamp, token e signature. Frontmail calcola l’HMAC-SHA256 di timestamp + token con la tua chiave di firma e rifiuta le richieste la cui firma non corrisponde. Senza la chiave di firma gli eventi non possono essere verificati e vengono ignorati.

Frontmail etichetta ogni messaggio con v:frontmail_message_id, così gli eventi vengono associati al messaggio giusto anche quando invii lo stesso modello molte volte.

Errori comuni

Frontmail classifica gli errori del provider in tre classi:

auth – il servizio non funziona (chiave API non valida, 401/403, dominio o regione errati, restrizioni della sandbox). Il servizio viene segnato come unhealthy e il proprietario riceve un’email più un banner nella dashboard. Se il modello ha un servizio di riserva, il messaggio viene inviato tramite quello; altrimenti il credito viene rimborsato e il messaggio aspetta nella coda dei messaggi in attesa come held_service_error, per essere inviato automaticamente dopo che avrai sistemato il servizio (ricontrollato al salvataggio e dal controllo di stato giornaliero).
permanent – questo messaggio non può essere inviato (destinatario non valido, errore di validazione 4xx). Se configurato, viene provato il servizio di riserva; altrimenti lo stato è failed e il credito viene rimborsato.
transient – timeout, 5xx, throttling 429. Ritentato con backoff esponenziale; esauriti i tentativi, il messaggio è failed e il credito viene rimborsato.

Risposta di Mailgun	Classe	Cosa fare
`401 Forbidden`	auth	La chiave API è errata, eliminata o appartiene a un altro account. Crea una nuova chiave e aggiorna il servizio.
`404 Domain not found: mg.example.com`	auth	Controlla come è scritto il dominio e la Regione (i domini UE richiedono `api.eu.mailgun.net`).
`400 Domain mg.example.com is not allowed to send: Free accounts are for test purposes only…`	auth	Dominio sandbox o account non verificato: aggiungi un destinatario autorizzato, verifica il tuo dominio o passa a un piano superiore.
`403` “account disabled / domain disabled”	auth	Mailgun ha sospeso l’invio; controlla la dashboard di Mailgun e contatta il loro supporto.
`400 'to' parameter is not a valid address`	permanent	L’indirizzo del destinatario non è valido: vedi destinatario non valido.
`413 Request Entity Too Large`	permanent	Il messaggio con gli allegati supera il limite di dimensione di Mailgun (25 MB).
`429 Too Many Requests`	transient	Throttling; Frontmail rispetta `Retry-After`. Abbassa Max email al secondo se succede spesso.
`500` / `502` / `503`, timeout	transient	Disservizio di Mailgun: non devi fare nulla, Frontmail ritenta.

Checklist

Dominio di invio proprio (ad es. mg.example.com) aggiunto e verificato in Mailgun
SPF, DKIM, MX e CNAME di tracciamento pubblicati; DMARC almeno p=none
La Regione in Frontmail corrisponde a quella del dominio
Chiave API privata con un ruolo limitato, non una domain sending key
Prova connessione va a buon fine
URL del webhook aggiunto per delivered, permanent failure, complaints (+ opens/clicks se servono)
Chiave di firma dei webhook copiata in Frontmail
L’indirizzo mittente nel modello è sul dominio verificato