Mailgun

Mailgun to usługa poczty transakcyjnej nastawiona na programistów. To dobry domyślny wybór dla Frontmail: proste API, regiony USA i UE, szczegółowe dane o zdarzeniach i webhooki dla doręczeń, odbić, skarg, otwarć i kliknięć.

Wybierz Mailgun, gdy wysyłasz pocztę transakcyjną (rejestracje, potwierdzenia płatności, powiadomienia, zgłoszenia z formularzy) z własnej domeny, chcesz śledzić odbicia i skargi i wolisz trzymać dane w UE (region Mailgun EU). Przy kilku e-mailach z prywatnej skrzynki prościej będzie użyć SMTP lub Gmaila. Porównanie znajdziesz w przeglądzie usług.

Wymagania

Konto Mailgun. Nowe konta zaczynają z domeną sandbox, która może wysyłać tylko do autoryzowanych odbiorców (zobacz Sandbox i limity).
Domena wysyłkowa dodana i zweryfikowana w Mailgunie – zalecamy subdomenę, np. mg.example.com, żeby reputacja i DNS domeny głównej pozostały osobno.
Klucz API. Utwórz osobny klucz dla Frontmail w Account settings → API security → Add new key (starszy interfejs: Account → API keys).
- Użyj klucza z najbardziej ograniczoną rolą, która nadal pozwala wysyłać i odczytywać informacje o domenie (np. Developer zamiast Admin).
- Domenowy sending key (Sending → Domain settings → Sending API keys) potrafi wysyłać, ale nie może odczytać domeny, więc Testuj połączenie i codzienny health check zgłoszą usługę jako niedziałającą. Użyj prywatnego klucza konta.
Opcjonalnie: HTTP webhook signing key z Sending → Webhooks do zdarzeń doręczeń.

Podłączenie we Frontmail

Otwórz Usługi e-mail → Dodaj usługę → Mailgun.
Wypełnij pola:

Pole	Gdzie je znaleźć	Przykład
Region	Region widoczny przy domenie w Mailgunie (Sending → Domains)	`UE (api.eu.mailgun.net)`
Domena wysyłkowa	Sending → Domains, dokładnie tak, jak jest tam zapisana	`mg.example.com`
Klucz API	Account settings → API security (wyświetlany tylko raz, przy tworzeniu)	`key-3ax6…` / `a1b2c3…-us`
Klucz podpisu webhooków	Sending → Webhooks → HTTP webhook signing key	`8c1f…`
Maks. liczba e-maili na sekundę	Opcjonalnie; domyślnie 10/s	`5`

Kliknij Zweryfikuj i zapisz – Frontmail odpyta API Mailgun o domenę i sprawdzi, czy klucz, region i domena do siebie pasują.
Usługa zostanie zapisana, gdy sprawdzenie się powiedzie. Dane dostępowe są szyfrowane kopertowo przez AWS KMS; odszyfrowuje je tylko proces wysyłki w chwili wysyłania.

Adres nadawcy w szablonie musi być w domenie wysyłkowej (np. hello@mg.example.com) – albo w domenie głównej, jeśli to ją zweryfikowano.

DNS: SPF, DKIM i DMARC

Mailgun pokazuje dokładne rekordy dla twojej domeny w Sending → Domains → DNS records. Dla mg.example.com wyglądają tak:

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

; DKIM – selector is generated per domain (e.g. pic, k1, smtp, mx)
pic._domainkey.mg.example.com.      TXT    "k=rsa; p=MIGfMA0GCSqGSIb3DQEB…"

; Receiving / bounce handling (recommended)
mg.example.com.                     MX 10  mxa.mailgun.org.
mg.example.com.                     MX 10  mxb.mailgun.org.     ; EU: mxa.eu.mailgun.org / mxb.eu.mailgun.org

; Open & click tracking
email.mg.example.com.               CNAME  mailgun.org.         ; EU: eu.mailgun.org

; DMARC – on the organizational domain, start with monitoring
_dmarc.example.com.                 TXT    "v=DMARC1; p=none; rua=mailto:dmarc@example.com"

Selektor DKIM skopiuj z Mailguna, a nie z tego przykładu – dla każdej domeny jest inny (pic._domainkey, k1._domainkey, …). Nowsze domeny mogą też korzystać z delegowanego DKIM przez CNAME z automatyczną rotacją kluczy.
Jeśli domena główna ma już SPF dla twojej skrzynki, nie szkodzi – subdomena ma własny rekord SPF.
Kliknij Verify DNS settings w Mailgunie; propagacja może trwać od minut do godzin.
Gdy raporty DMARC będą czyste, zaostrz politykę do p=quarantine, a później p=reject.

Regiony

Mailgun działa w dwóch całkowicie oddzielnych regionach:

Region	Host API	Kiedy używać
US	`api.mailgun.net`	domena została utworzona w regionie US (domyślnie)
EU	`api.eu.mailgun.net`	domena została utworzona w regionie EU (dane zostają w UE)

Domena istnieje dokładnie w jednym regionie, więc wybierz region, w którym ją utworzono. Niezgodność zwraca 404 Domain not found, co Frontmail traktuje jako błąd auth. Regionu nie da się później zmienić – żeby się przenieść, dodaj domenę ponownie w drugim regionie.

Sandbox i limity

Domena sandbox (sandbox123….mailgun.org): wysyła tylko do autoryzowanych odbiorców (maks. 5), którzy potwierdzili e-mail z zaproszeniem. Wszystko inne kończy się błędem „Free accounts are for test purposes only”. Dobre do pierwszego testu, nie do produkcji.
Darmowy plan: około 100 e-maili dziennie.
Nowe konta / domeny mogą mieć ograniczone tempo wysyłki, dopóki nie zbudujesz historii wysyłek albo nie przejdziesz weryfikacji firmy.
Domyślne tempo Frontmail dla Mailguna to 10 wiadomości na sekundę na usługę; jeśli Mailgun cię dławi, obniż je w Maks. liczba e-maili na sekundę.

Webhooki (śledzenie doręczeń)

Mailgun może zgłaszać, co się stało po przyjęciu wiadomości.

Skopiuj URL webhooka ze strony usługi we Frontmail (przycisk kopiowania obok URL webhooka). Wygląda tak:
```
https://api.frontmail.dev/webhooks/providers/mailgun/<token>
```
<token> jest unikalny dla tej usługi – nie używaj go w kilku usługach.
W Mailgunie otwórz Sending → Webhooks, wybierz właściwą domenę (i region) i dodaj URL dla tych zdarzeń:

Zdarzenie Mailgun	Zdarzenie Frontmail
Delivered	`delivered`
Permanent failure	`bounced` – adres zostaje dodany do listy wykluczeń
Temporary failure	zapisywane przy wiadomości; Mailgun dalej ponawia
Spam complaints	`complained` – dodany do listy wykluczeń
Opens	`opened` (wymaga śledzenia otwarć w domenie)
Clicks	`clicked` (wymaga śledzenia kliknięć w domenie)

Skopiuj HTTP webhook signing key z tej samej strony do pola Klucz podpisu webhooków usługi we Frontmail.

Weryfikacja podpisu: każdy webhook Mailgun zawiera timestamp, token i signature. Frontmail oblicza HMAC-SHA256 z timestamp + token twoim kluczem podpisu i odrzuca żądania, których podpis się nie zgadza. Bez klucza podpisu zdarzeń nie da się zweryfikować i są ignorowane.

Frontmail oznacza każdą wiadomość zmienną v:frontmail_message_id, więc zdarzenia trafiają do właściwej wiadomości nawet wtedy, gdy ten sam szablon wysyłasz wiele razy.

Częste błędy

Frontmail dzieli błędy dostawców na trzy klasy:

auth – usługa nie działa (nieprawidłowy klucz API, 401/403, zła domena lub region, ograniczenia sandboxa). Usługa zostaje oznaczona jako unhealthy, a właściciel dostaje e-mail i baner w panelu. Jeśli szablon ma usługę zapasową, wiadomość idzie przez nią; w przeciwnym razie kredyt wraca, a wiadomość czeka w kolejce wstrzymanych wiadomości jako held_service_error i zostanie wysłana automatycznie po naprawieniu usługi (sprawdzanej ponownie przy zapisie i w codziennym health checku).
permanent – tej wiadomości nie da się wysłać (nieprawidłowy odbiorca, błąd walidacji 4xx). Jeśli skonfigurowano usługę zapasową, zostanie użyta; w przeciwnym razie status to failed, a kredyt wraca.
transient – timeouty, 5xx, throttling 429. Ponawiane z wykładniczym opóźnieniem; po wyczerpaniu prób wiadomość ma status failed, a kredyt wraca.

Odpowiedź Mailgun	Klasa	Co zrobić
`401 Forbidden`	auth	Klucz API jest błędny, usunięty albo należy do innego konta. Utwórz nowy klucz i zaktualizuj usługę.
`404 Domain not found: mg.example.com`	auth	Sprawdź pisownię domeny i Region (domeny EU wymagają `api.eu.mailgun.net`).
`400 Domain mg.example.com is not allowed to send: Free accounts are for test purposes only…`	auth	Domena sandbox lub niezweryfikowane konto – dodaj autoryzowanego odbiorcę, zweryfikuj własną domenę albo przejdź na wyższy plan.
`403` „account disabled / domain disabled”	auth	Mailgun wstrzymał wysyłkę; sprawdź panel Mailgun i skontaktuj się z ich pomocą techniczną.
`400 'to' parameter is not a valid address`	permanent	Adres odbiorcy ma błędny format – zobacz nieprawidłowy odbiorca.
`413 Request Entity Too Large`	permanent	Wiadomość z załącznikami przekracza limit rozmiaru Mailguna (25 MB).
`429 Too Many Requests`	transient	Dławienie; Frontmail respektuje `Retry-After`. Jeśli zdarza się to często, obniż Maks. liczba e-maili na sekundę.
`500` / `502` / `503`, timeout	transient	Awaria Mailguna – nic nie musisz robić, Frontmail ponawia próby.

Lista kontrolna

Własna domena wysyłkowa (np. mg.example.com) dodana i zweryfikowana w Mailgunie
Opublikowane SPF, DKIM, MX i CNAME do śledzenia; DMARC co najmniej p=none
Region we Frontmail zgodny z regionem domeny
Prywatny klucz API z ograniczoną rolą, a nie domenowy sending key
Testuj połączenie przechodzi
URL webhooka dodany dla delivered, permanent failure, complaints (+ opens/clicks w razie potrzeby)
Klucz podpisu webhooków skopiowany do Frontmail
Adres nadawcy w szablonie jest w zweryfikowanej domenie