Przegląd usług

Usługa to połączenie między Frontmail a dostawcą poczty. Frontmail nigdy nie wysyła e-maili w twoim imieniu z własnej infrastruktury – renderuje twój szablon i przekazuje wiadomość twojemu dostawcy, więc dostarczalność, reputacja nadawcy i cennik dostawcy pozostają pod twoją kontrolą.

Obsługiwani dostawcy

Dostawca	Typ	Najlepszy do	Webhooki doręczeń
SMTP (Seznam, Zoho, własny)	`smtp`	Istniejące skrzynki, własne serwery poczty	–
Mailgun	`mailgun`	Poczta transakcyjna, region UE lub USA	✓
Amazon SES	`ses`	Duże wolumeny niskim kosztem, użytkownicy AWS	✓ (przez SNS)
Postmark	`postmark`	Szybkie doręczanie transakcyjne	✓
Mailjet	`mailjet`	Transakcyjne z siedzibą w UE	✓
Brevo	`brevo`	Z siedzibą w UE, hojny darmowy plan	✓
Resend	`resend`	API przyjazne programistom	✓
Gmail (OAuth)	`gmail`	Skrzynki prywatne / Google Workspace	–
Outlook / Microsoft 365 (OAuth)	`outlook`	Skrzynki Outlook.com i Microsoft 365	–

Usługi osobiste (skrzynki SMTP, Gmail, Outlook) szybko się konfiguruje i wysyłają z twojej prawdziwej skrzynki, ale mają niskie dzienne limity i brak śledzenia doręczeń. Dostawcy transakcyjni wymagają konfiguracji DNS, za to się skalują, dają zdarzenia doręczeń, odbić i otwarć oraz lepszą dostarczalność.

Dodawanie usługi

Właściciel, administratorzy i programiści zarządzają usługami w Usługi e-mail.

Kliknij Dodaj usługę i wybierz dostawcę.
W przypadku Gmaila i Outlooka kliknij Połącz z Gmail / Połącz z Outlook / Microsoft 365 i zezwól na dostęp w oknie dostawcy. Dla pozostałych wpisz dane dostępowe i kliknij Zweryfikuj i zapisz – Frontmail sprawdza je u dostawcy (bez wysyłania e-maila) przed zapisaniem. Jeśli chcesz sprawdzić je później, możesz użyć Zapisz bez weryfikacji. Dane dostępowe są szyfrowane przez AWS KMS (szyfrowanie kopertowe, AES-256-GCM) i nigdy więcej nie są wyświetlane – możesz je tylko zastąpić.
Na stronie usługi Testuj połączenie w każdej chwili uruchamia to samo sprawdzenie ponownie.
Opcjonalnie skonfiguruj URL webhooka widoczny na stronie usługi (zobacz niżej).
Twoja pierwsza usługa automatycznie staje się domyślną; zmienisz to przyciskiem Ustaw jako domyślną. Używają jej szablony bez jawnie wybranej usługi – i wywołania API bez service_id. Usunięcie usługi, z której korzystają szablony, przełącza je na usługę domyślną.

Domyślny nadawca (From)

Każda usługa może mieć Domyślny adres nadawcy i Domyślną nazwę nadawcy (w formularzu dodawania i na stronie usługi w sekcji Ustawienia). Adres nadawcy każdego e-maila jest ustalany w tej kolejności:

E-mail nadawcy / Nazwa nadawcy w ustawieniach szablonu (mogą używać parametrów),
Domyślny adres / nazwa nadawcy usługi,
w przypadku Gmaila i Outlooka podłączone konto; w przypadku SMTP nazwa użytkownika, jeśli jest adresem e-mail.

Dopóki pole e-mail nadawcy w szablonie jest puste, edytor szablonu pokazuje, który nadawca zostanie użyty. Zmiana samego domyślnego nadawcy nie uruchamia ponownie testu połączenia. Jeśli żaden krok nie da adresu, wysyłki testowe kończą się błędem sender_not_configured, a prawdziwe wysyłki kończą się trwałym błędem (kredyt wraca).

Usługa zapasowa (failover)

Każdy szablon ma usługę główną i opcjonalną usługę zapasową, obie wybierane w edytorze szablonu w Ustawienia → Doręczanie (Usługa i Usługa zapasowa). Najpierw próbowana jest usługa główna. Jeśli zawiedzie z błędem uwierzytelniania lub trwałym, ta sama wiadomość jest od razu wysyłana przez usługę zapasową. Oś czasu wiadomości pokazuje zdarzenie failover, a Historia – która usługa faktycznie ją wysłała.

Błędy przejściowe (timeouty, throttling, 5xx) nie uruchamiają failoveru – najpierw są ponawiane w usłudze głównej, bo zwykle mijają same.

Jak obsługiwane są błędy dostawców

Frontmail klasyfikuje każdy błąd dostawcy do jednej z trzech grup:

Klasa	Przykłady	Co robi Frontmail
Uwierzytelnianie	nieprawidłowy lub unieważniony klucz API, wygasły token OAuth (Google `invalid_grant`), SMTP `535`	Oznacza usługę jako niesprawną (Nie działa), wysyła e-mail właścicielowi i administratorom, pokazuje baner w panelu. Wysyła przez usługę zapasową, jeśli jest; w przeciwnym razie zwraca kredyt i zatrzymuje wiadomość jako `held_service_error`.
Trwały	nieprawidłowy odbiorca, niezweryfikowany nadawca lub domena, wiadomość odrzucona przez politykę	Próbuje usługi zapasowej, jeśli jest; w przeciwnym razie wiadomość dostaje status `failed`, a kredyt wraca. Twarde odbicia dodają adres do listy wykluczeń.
Przejściowy	timeout, zerwane połączenie, `5xx` dostawcy, throttling `429`, SMTP `421`/`450`/`451`	Ponawia z wykładniczym opóźnieniem (z poszanowaniem limitów dostawcy). Jeśli wszystkie próby zawiodą, wiadomość dostaje status `failed`, a kredyt wraca.

Każdy przewodnik po dostawcy wymienia jego częste błędy i ich klasyfikację.

Wiadomości wstrzymane z powodu błędu usługi

Wiadomości w stanie held_service_error czekają w kolejce wstrzymanych wiadomości razem z wiadomościami wstrzymanymi z powodu kredytów, oznaczone powodem usługa. Gdy tylko usługa znów działa – po aktualizacji danych dostępowych, ponownym połączeniu OAuth albo udanym health checku – są zwalniane automatycznie: ponownie rezerwowany jest kredyt i wychodzą w pierwotnej kolejności. Możesz je też zwolnić lub odrzucić ręcznie. Wygasają jak inne wstrzymane wiadomości (Free 3 dni, plany płatne 14 dni), a przed tym dostaniesz e-mail.

Health checki

Codziennie: Frontmail sprawdza każdą usługę (tak samo jak Testuj połączenie).
Od razu po błędzie uwierzytelniania podczas wysyłki.
Przy zapisie: za każdym razem, gdy edytujesz dane dostępowe lub ponownie łączysz OAuth.

Usługa ma stan healthy (Działa), unhealthy (Nie działa) lub unknown (Nie sprawdzono). Gdy usługa przestaje działać, właściciel i administratorzy dostają e-mail, a panel do czasu jej naprawy pokazuje baner Usługa e-mail nie działa z przyciskiem Napraw usługę; kolejny e-mail dostaniesz, gdy usługa znów zadziała, a jej wstrzymane wiadomości zostaną zwolnione.

Webhooki doręczeń

Dostawcy transakcyjni mogą zgłaszać, co się stało po przyjęciu wiadomości. Skopiuj URL webhooka ze strony usługi (jest tam też lista zdarzeń do włączenia) do konsoli swojego dostawcy:

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

<type> to typ dostawcy z tabeli powyżej (np. mailgun), <token> to losowy token unikalny dla usługi – traktuj cały URL jak sekret. Frontmail dodatkowo weryfikuje podpis dostawcy, jeśli dostawca go obsługuje.

Zdarzenia są mapowane na statusy wiadomości i statystyki:

Zdarzenie dostawcy	Frontmail
delivered	status `delivered`
hard bounce	status `bounced` + adres dodany do listy wykluczeń
soft bounce	tylko zdarzenie (dostawca ponawia)
spam complaint	status `complained` + adres dodany do listy wykluczeń
open / click	zdarzenia `opened` / `clicked` na osi czasu i w statystykach

Bez webhooków wiadomość kończy w stanie sent – co oznacza, że dostawca ją przyjął.