Mailgun

Mailgun je transakční e-mailová služba stavěná pro vývojáře. Pro Frontmail je to dobrá výchozí volba: jednoduché API, region v USA i v EU, podrobná data o událostech a webhooky pro doručení, bounce, stížnosti, otevření i kliknutí.

Mailgun zvolte, když posíláte transakční poštu (registrace, účtenky, notifikace, odeslané formuláře) z vlastní domény, chcete sledovat bounce a stížnosti a data chcete mít v EU (region EU). Na pár e-mailů z osobní schránky je jednodušší SMTP nebo Gmail. Srovnání najdete v přehledu služeb.

Co budete potřebovat

Účet u Mailgunu. Nové účty začínají se sandboxovou doménou, která smí posílat jen autorizovaným příjemcům (viz Sandbox a limity).
Odesílací doménu přidanou a ověřenou v Mailgunu – doporučujeme subdoménu, třeba mg.example.cz. Reputace i DNS hlavní domény tak zůstanou oddělené.
API klíč. Pro Frontmail si vytvořte samostatný klíč v Account settings → API security → Add new key (ve starším rozhraní Account → API keys).
- Zvolte co nejužší roli, která ještě umí odesílat a číst informace o doméně (např. Developer, ne Admin).
- Doménový sending key (Sending → Domain settings → Sending API keys) sice odesílat umí, ale doménu nepřečte – Otestovat spojení i denní kontrola stavu by ho vyhodnotily jako nefunkční. Použijte privátní klíč účtu.
Volitelně HTTP webhook signing key ze stránky Sending → Webhooks pro události o doručení.

Připojení ve Frontmailu

Otevřete E-mailové služby → Přidat službu → Mailgun.
Vyplňte pole:

Pole	Kde ho najdete	Příklad
Region	Region uvedený u domény v Mailgunu (Sending → Domains)	`EU (api.eu.mailgun.net)`
Odesílací doména	Sending → Domains, přesně jak je tam uvedená	`mg.example.cz`
API klíč	Account settings → API security (zobrazí se jen jednou při vytvoření)	`key-3ax6…` / `a1b2c3…-us`
Podpisový klíč webhooků	Sending → Webhooks → HTTP webhook signing key	`8c1f…`
Max. e-mailů za sekundu	Volitelné; výchozí 10/s	`5`

Klikněte na Ověřit a uložit – Frontmail se zeptá Mailgun API na doménu a ověří, že klíč, region a doména k sobě sedí.
Když kontrola projde, služba se uloží. Přístupové údaje šifrujeme obálkovým šifrováním přes AWS KMS; dešifruje je jen odesílací proces v okamžiku odeslání.

Adresa Od v šabloně musí být na odesílací doméně (např. ahoj@mg.example.cz) – případně na hlavní doméně, pokud jste ověřili tu.

DNS: SPF, DKIM a DMARC

Přesné záznamy pro vaši doménu ukáže Mailgun v Sending → Domains → DNS records. Pro mg.example.cz vypadají zhruba takto:

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

; DKIM – selektor se generuje pro každou doménu (např. pic, k1, smtp, mx)
pic._domainkey.mg.example.cz.       TXT    "k=rsa; p=MIGfMA0GCSqGSIb3DQEB…"

; Příjem / zpracování bounců (doporučeno)
mg.example.cz.                      MX 10  mxa.mailgun.org.
mg.example.cz.                      MX 10  mxb.mailgun.org.     ; EU: mxa.eu.mailgun.org / mxb.eu.mailgun.org

; Sledování otevření a kliknutí
email.mg.example.cz.                CNAME  mailgun.org.         ; EU: eu.mailgun.org

; DMARC – na organizační doméně, začněte monitoringem
_dmarc.example.cz.                  TXT    "v=DMARC1; p=none; rua=mailto:dmarc@example.cz"

DKIM selektor opište z Mailgunu, ne z tohoto příkladu – každá doména má jiný (pic._domainkey, k1._domainkey…). Novější domény umí i delegované DKIM přes CNAME s automatickou rotací klíčů.
Pokud už má hlavní doména SPF pro vaši schránku, nevadí to – subdoména má vlastní SPF záznam.
V Mailgunu klikněte na Verify DNS settings; propagace trvá od minut po hodiny.
Až budou DMARC reporty čisté, zpřísněte politiku na p=quarantine a později p=reject.

Regiony

Mailgun provozuje dva zcela oddělené regiony:

Region	API server	Kdy ho použít
USA	`api.mailgun.net`	doména byla založena v americkém regionu (výchozí)
EU	`api.eu.mailgun.net`	doména byla založena v evropském regionu (data zůstávají v EU)

Každá doména existuje právě v jednom regionu, zvolte tedy region, ve kterém jste doménu založili. Při nesouladu vrátí Mailgun 404 Domain not found a Frontmail to vyhodnotí jako chybu přihlášení (auth). Region nejde dodatečně změnit – pro přesun doménu přidejte znovu v druhém regionu.

Sandbox a limity

Sandboxová doména (sandbox123….mailgun.org): posílá jen autorizovaným příjemcům (nejvýš 5), kteří potvrdili pozvánku e-mailem. Cokoli jiného skončí chybou „Free accounts are for test purposes only“. Na první test dobré, na produkci ne.
Bezplatný tarif: zhruba 100 e-mailů denně.
Nové účty a domény může Mailgun přibrzdit, dokud nemají historii odesílání nebo neprojdou ověřením firmy.
Výchozí rychlost Frontmailu pro Mailgun je 10 zpráv za sekundu na službu; pokud vás Mailgun brzdí, snižte Max. e-mailů za sekundu.

Webhooky (sledování doručení)

Mailgun umí dát vědět, co se se zprávou dělo po jejím přijetí.

Na stránce služby ve Frontmailu zkopírujte webhook URL (tlačítko pro kopírování u Webhook URL). Vypadá takto:
```
https://api.frontmail.dev/webhooks/providers/mailgun/<token>
```
<token> je jedinečný pro tuto službu – nesdílejte ho mezi službami.
V Mailgunu otevřete Sending → Webhooks, vyberte správnou doménu (a region) a přidejte URL pro tyto události:

Událost v Mailgunu	Událost ve Frontmailu
Delivered	`delivered`
Permanent failure	`bounced` – adresa se přidá na suppression list
Temporary failure	zaznamená se u zprávy; Mailgun to dál zkouší
Spam complaints	`complained` – přidá se na suppression list
Opens	`opened` (vyžaduje zapnuté sledování otevření u domény)
Clicks	`clicked` (vyžaduje zapnuté sledování kliknutí u domény)

Ze stejné stránky zkopírujte HTTP webhook signing key do pole Podpisový klíč webhooků ve Frontmailu.

Ověření podpisu: každý webhook Mailgunu nese timestamp, token a signature. Frontmail spočítá HMAC-SHA256 z timestamp + token vaším podpisovým klíčem a požadavky s nesouhlasným podpisem odmítne. Bez podpisového klíče nejde události ověřit a ignorujeme je.

Každou zprávu Frontmail označí proměnnou v:frontmail_message_id, takže se události spárují se správnou zprávou, i když stejnou šablonu posíláte mnohokrát.

Časté chyby

Frontmail chyby poskytovatele řadí do tří tříd:

auth – nefunguje služba (neplatný API klíč, 401/403, špatná doména nebo region, omezení sandboxu). Služba se označí jako unhealthy a vlastník dostane e-mail a upozornění v dashboardu. Má-li šablona záložní službu, zpráva odejde přes ni; jinak vrátíme kredit a zpráva počká ve frontě zadržených zpráv jako held_service_error. Po opravě služby se odešle automaticky (ověřujeme při uložení a při denní kontrole stavu).
permanent – nejde odeslat právě tahle zpráva (neplatný příjemce, validační chyba 4xx). Zkusí se záložní služba, pokud ji máte; jinak je zpráva failed a kredit se vrátí.
transient – timeouty, 5xx, throttling 429. Opakujeme s exponenciálně rostoucí pauzou; po vyčerpání pokusů je zpráva failed a kredit se vrátí.

Odpověď Mailgunu	Třída	Co dělat
`401 Forbidden`	auth	API klíč je špatný, smazaný nebo patří jinému účtu. Vytvořte nový a službu aktualizujte.
`404 Domain not found: mg.example.cz`	auth	Zkontrolujte název domény a Region (evropské domény potřebují `api.eu.mailgun.net`).
`400 Domain mg.example.cz is not allowed to send: Free accounts are for test purposes only…`	auth	Sandboxová doména nebo neověřený účet – přidejte autorizovaného příjemce, ověřte vlastní doménu nebo přejděte na placený tarif.
`403` „account disabled / domain disabled“	auth	Mailgun pozastavil odesílání; podívejte se do jeho dashboardu a kontaktujte podporu.
`400 'to' parameter is not a valid address`	permanent	Adresa příjemce je chybně zapsaná – viz neplatný příjemce.
`413 Request Entity Too Large`	permanent	Zpráva i s přílohami překračuje limit Mailgunu (25 MB).
`429 Too Many Requests`	transient	Omezení rychlosti; Frontmail respektuje `Retry-After`. Stává-li se to často, snižte Max. e-mailů za sekundu.
`500` / `502` / `503`, timeout	transient	Výpadek Mailgunu – nic nedělejte, Frontmail to zopakuje.

Kontrolní seznam

Vlastní odesílací doména (např. mg.example.cz) přidaná a ověřená v Mailgunu
SPF, DKIM, MX a CNAME pro sledování nastavené; DMARC aspoň p=none
Region ve Frontmailu odpovídá regionu domény
Privátní API klíč s omezenou rolí, ne doménový sending key
Otestovat spojení prošel
Webhook URL přidaná pro delivered, permanent failure, stížnosti (případně opens/clicks)
Podpisový klíč webhooků zkopírovaný do Frontmailu
Adresa Od v šabloně je na ověřené doméně