Mailgun

Mailgun je transakčná e-mailová služba stavaná pre vývojárov. Pre Frontmail je to dobrá predvolená voľba: jednoduché API, región v USA aj v EÚ, podrobné dáta o udalostiach a webhooky pre doručenie, bounce, sťažnosti, otvorenia aj kliknutia.

Mailgun zvoľte, keď posielate transakčnú poštu (registrácie, účtenky, notifikácie, odoslané formuláre) z vlastnej domény, chcete sledovať bounce a sťažnosti a dáta chcete mať v EÚ (región EÚ). Na pár e-mailov z osobnej schránky je jednoduchší SMTP alebo Gmail. Porovnanie nájdete v prehľade služieb.

Čo budete potrebovať

Účet v Mailgune. Nové účty začínajú so sandboxovou doménou, ktorá smie posielať len autorizovaným príjemcom (pozri Sandbox a limity).
Odosielaciu doménu pridanú a overenú v Mailgune – odporúčame subdoménu, napríklad mg.example.sk. Reputácia aj DNS hlavnej domény tak zostanú oddelené.
API kľúč. Pre Frontmail si vytvorte samostatný kľúč v Account settings → API security → Add new key (v staršom rozhraní Account → API keys).
- Zvoľte čo najužšiu rolu, ktorá ešte vie odosielať a čítať informácie o doméne (napr. Developer, nie Admin).
- Doménový sending key (Sending → Domain settings → Sending API keys) síce odosielať vie, ale doménu neprečíta – Otestovať pripojenie aj denná kontrola stavu by ho vyhodnotili ako nefunkčný. Použite privátny kľúč účtu.
Voliteľne HTTP webhook signing key zo stránky Sending → Webhooks pre udalosti o doručení.

Pripojenie vo Frontmaile

Otvorte E-mailové služby → Pridať službu → Mailgun.
Vyplňte polia:

Pole	Kde ho nájdete	Príklad
Región	Región uvedený pri doméne v Mailgune (Sending → Domains)	`EÚ (api.eu.mailgun.net)`
Odosielacia doména	Sending → Domains, presne tak, ako je tam uvedená	`mg.example.sk`
API kľúč	Account settings → API security (zobrazí sa len raz pri vytvorení)	`key-3ax6…` / `a1b2c3…-us`
Podpisový kľúč webhookov	Sending → Webhooks → HTTP webhook signing key	`8c1f…`
Max. e-mailov za sekundu	Voliteľné; predvolene 10/s	`5`

Kliknite na Overiť a uložiť – Frontmail sa opýta Mailgun API na doménu a overí, že kľúč, región a doména k sebe sedia.
Keď kontrola prejde, služba sa uloží. Prístupové údaje šifrujeme obálkovým šifrovaním cez AWS KMS; dešifruje ich len odosielací proces v okamihu odoslania.

Adresa odosielateľa v šablóne musí byť na odosielacej doméne (napr. ahoj@mg.example.sk) – prípadne na hlavnej doméne, ak ste overili tú.

DNS: SPF, DKIM a DMARC

Presné záznamy pre vašu doménu ukáže Mailgun v Sending → Domains → DNS records. Pre mg.example.sk vyzerajú približne takto:

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

; DKIM – selektor sa generuje pre každú doménu (napr. pic, k1, smtp, mx)
pic._domainkey.mg.example.sk.       TXT    "k=rsa; p=MIGfMA0GCSqGSIb3DQEB…"

; Príjem / spracovanie bounce (odporúčané)
mg.example.sk.                      MX 10  mxa.mailgun.org.
mg.example.sk.                      MX 10  mxb.mailgun.org.     ; EU: mxa.eu.mailgun.org / mxb.eu.mailgun.org

; Sledovanie otvorení a kliknutí
email.mg.example.sk.                CNAME  mailgun.org.         ; EU: eu.mailgun.org

; DMARC – na organizačnej doméne, začnite monitoringom
_dmarc.example.sk.                  TXT    "v=DMARC1; p=none; rua=mailto:dmarc@example.sk"

DKIM selektor skopírujte z Mailgunu, nie z tohto príkladu – každá doména má iný (pic._domainkey, k1._domainkey…). Novšie domény vedia aj delegovaný DKIM cez CNAME s automatickou rotáciou kľúčov.
Ak už má hlavná doména SPF pre vašu schránku, neprekáža to – subdoména má vlastný SPF záznam.
V Mailgune kliknite na Verify DNS settings; propagácia trvá od minút po hodiny.
Keď budú DMARC reporty čisté, sprísnite politiku na p=quarantine a neskôr p=reject.

Regióny

Mailgun prevádzkuje dva úplne oddelené regióny:

Región	API server	Kedy ho použiť
USA	`api.mailgun.net`	doména bola založená v americkom regióne (predvolený)
EÚ	`api.eu.mailgun.net`	doména bola založená v európskom regióne (dáta zostávajú v EÚ)

Každá doména existuje práve v jednom regióne, zvoľte teda región, v ktorom ste doménu založili. Pri nesúlade vráti Mailgun 404 Domain not found a Frontmail to vyhodnotí ako chybu autentifikácie (auth). Región sa nedá dodatočne zmeniť – ak chcete doménu presunúť, pridajte ju znova v druhom regióne.

Sandbox a limity

Sandboxová doména (sandbox123….mailgun.org): posiela len autorizovaným príjemcom (najviac 5), ktorí potvrdili pozvánku e-mailom. Čokoľvek iné skončí chybou „Free accounts are for test purposes only“. Na prvý test dobré, na produkciu nie.
Bezplatný tarif: približne 100 e-mailov denne.
Nové účty a domény môže Mailgun pribrzdiť, kým nemajú históriu odosielania alebo neprejdú overením firmy.
Predvolená rýchlosť Frontmailu pre Mailgun je 10 správ za sekundu na službu; ak vás Mailgun brzdí, znížte Max. e-mailov za sekundu.

Webhooky (sledovanie doručenia)

Mailgun vie dať vedieť, čo sa so správou dialo po jej prijatí.

Na stránke služby vo Frontmaile skopírujte URL webhooku (tlačidlo na kopírovanie pri URL webhooku). Vyzerá takto:
```
https://api.frontmail.dev/webhooks/providers/mailgun/<token>
```
<token> je jedinečný pre túto službu – nezdieľajte ho medzi službami.
V Mailgune otvorte Sending → Webhooks, vyberte správnu doménu (a región) a pridajte URL pre tieto udalosti:

Udalosť v Mailgune	Udalosť vo Frontmaile
Delivered	`delivered`
Permanent failure	`bounced` – adresa sa pridá do zoznamu blokovaných adries
Temporary failure	zaznamená sa pri správe; Mailgun to ďalej skúša
Spam complaints	`complained` – pridá sa do zoznamu blokovaných adries
Opens	`opened` (vyžaduje zapnuté sledovanie otvorení pri doméne)
Clicks	`clicked` (vyžaduje zapnuté sledovanie kliknutí pri doméne)

Z rovnakej stránky skopírujte HTTP webhook signing key do poľa Podpisový kľúč webhookov vo Frontmaile.

Overenie podpisu: každý webhook Mailgunu nesie timestamp, token a signature. Frontmail vypočíta HMAC-SHA256 z timestamp + token vaším podpisovým kľúčom a požiadavky s nezhodným podpisom odmietne. Bez podpisového kľúča sa udalosti nedajú overiť a ignorujeme ich.

Každú správu Frontmail označí premennou v:frontmail_message_id, takže sa udalosti spárujú so správnou správou, aj keď rovnakú šablónu posielate mnohokrát.

Časté chyby

Frontmail chyby poskytovateľa triedi do troch tried:

auth – nefunguje služba (neplatný API kľúč, 401/403, nesprávna doména alebo región, obmedzenia sandboxu). Služba sa označí ako unhealthy, vlastník dostane e-mail a upozornenie v dashboarde. Ak má šablóna záložnú službu, správa odíde cez ňu; inak vrátime kredit a správa počká vo fronte pozdržaných e-mailov ako held_service_error. Po oprave služby sa odošle automaticky (overujeme pri uložení a pri dennej kontrole stavu).
permanent – nedá sa odoslať práve táto správa (neplatný príjemca, validačná chyba 4xx). Skúsi sa záložná služba, ak ju máte; inak je správa failed a kredit sa vráti.
transient – timeouty, 5xx, throttling 429. Opakujeme s exponenciálne rastúcou pauzou; po vyčerpaní pokusov je správa failed a kredit sa vráti.

Odpoveď Mailgunu	Trieda	Čo robiť
`401 Forbidden`	auth	API kľúč je nesprávny, zmazaný alebo patrí inému účtu. Vytvorte nový a službu aktualizujte.
`404 Domain not found: mg.example.sk`	auth	Skontrolujte názov domény a Región (európske domény potrebujú `api.eu.mailgun.net`).
`400 Domain mg.example.sk is not allowed to send: Free accounts are for test purposes only…`	auth	Sandboxová doména alebo neoverený účet – pridajte autorizovaného príjemcu, overte vlastnú doménu alebo prejdite na platený tarif.
`403` „account disabled / domain disabled“	auth	Mailgun pozastavil odosielanie; pozrite sa do jeho dashboardu a kontaktujte podporu.
`400 'to' parameter is not a valid address`	permanent	Adresa príjemcu je chybne zapísaná – pozri neplatný príjemca.
`413 Request Entity Too Large`	permanent	Správa aj s prílohami prekračuje limit Mailgunu (25 MB).
`429 Too Many Requests`	transient	Rate limit; Frontmail rešpektuje `Retry-After`. Ak sa to stáva často, znížte Max. e-mailov za sekundu.
`500` / `502` / `503`, timeout	transient	Výpadok Mailgunu – netreba nič robiť, Frontmail to zopakuje.

Kontrolný zoznam

Vlastná odosielacia doména (napr. mg.example.sk) pridaná a overená v Mailgune
SPF, DKIM, MX a CNAME na sledovanie zverejnené; DMARC aspoň p=none
Región vo Frontmaile zodpovedá regiónu domény
Privátny API kľúč s obmedzenou rolou, nie doménový sending key
Otestovať pripojenie prešlo
URL webhooku pridaná pre delivered, permanent failure, sťažnosti (prípadne opens/clicks)
Podpisový kľúč webhookov skopírovaný do Frontmailu
Adresa odosielateľa v šablóne je na overenej doméne