Poradnik
Jak zbudować niezawodny system e-mail w produkcji
Praktyczny poradnik po całym cyklu operacyjnym: od wyboru wiadomości i uwierzytelnienia wysyłki, przez rozdzielenie strumieni, po obsługę dostarczania wiadomości, zdarzeń i higieny listy.
Autor: Wojtek Blazalek
Typy maili: transakcyjne vs marketingowe
Kluczowe rozróżnienie między mailem, na który użytkownik czeka, a tym, który chcesz, żeby przeczytał. Do tego ramy prawne, „szara strefa” maili hybrydowych i wpływ na infrastrukturę wysyłki.
Czytaj rozdziałJakich maili transakcyjnych potrzebuje Twoja aplikacja?
Wybierz zestaw podstawowy dla typu aplikacji, a potem określ w katalogu zdarzenie, cel i minimalny zakres informacji dla każdego maila transakcyjnego.
Czytaj rozdziałDostarczalność
Cztery filary trafiania do skrzynki odbiorczej: uwierzytelnianie SPF/DKIM/DMARC, reputacja nadawcy, obsługa odbić i skarg oraz architektura DNS chroniąca pocztę transakcyjną.
Czytaj rozdziałZarządzanie listą
Utrzymywanie list w czystości: listy supresji, automatyczna higiena, retencja danych i rozdzielenie strumieni transakcyjnych od marketingowych, by nie podkopywać reputacji nadawcy.
Czytaj rozdziałProjektowanie maili transakcyjnych
Jak robić maile, których użytkownik oczekuje: jasne, szybkie i nastawione na działanie. Tematy, struktura, podejście mobile-first, prezentacja OTP/CTA i obsługa błędów.
Czytaj rozdziałPozyskiwanie adresów
Odpowiedzialne zbieranie adresów: walidacja po stronie klienta i serwera, weryfikacja przez double opt-in, projektowanie formularzy bez dark patterns i prawidłowe zbieranie zgody.
Czytaj rozdziałMaile marketingowe
Praktyka programu opartego na zgodzie: jak zbierać opt-in, robić bezbolesny wypis, projektować wartościowe wiadomości i utrzymać listę w zdrowiu, by maile dalej trafiały do skrzynki.
Czytaj rozdziałZgodność prawna
Streszczenie najważniejszych reżimów (CAN-SPAM, RODO, CASL i inne): zasady wypisu, rejestrowanie zgód i techniczne nagłówki wymagane dziś od nadawców masowych.
Czytaj rozdziałNiezawodność wysyłki
Wysyłka jako problem systemów rozproszonych: idempotencja (zero duplikatów), ponawianie z backoffem, obsługa kodów błędów i kolejkowanie odseparowane od ścieżki żądania.
Czytaj rozdziałWebhooki i zdarzenia
Druga połowa historii maila: typy zdarzeń, weryfikacja podpisów, nienegocjowalne idempotentne przetwarzanie oraz reagowanie na odbicia i skargi, by lista supresji była dokładna.
Czytaj rozdziałJak korzystać z poradnika
Cztery ścieżki w zależności od tego, co teraz budujesz lub naprawiasz.
Nowa aplikacja
Zacznij od rozdziałów 01 i 02 (jakie maile są potrzebne), a potem 03 (uwierzytelnianie DNS) przed pierwszą wysyłką.
Problemy ze spamem
Rozdział 03 (Dostarczalność). Najczęstsza przyczyna to braki w uwierzytelnianiu.
Maile marketingowe
Ścieżka 06 (Pozyskiwanie adresów) → 08 (Zgodność prawna) → 07 (Maile marketingowe).
Produkcja
09 (Niezawodność wysyłki) → 10 (Webhooki i zdarzenia) → 04 (Zarządzanie listą).
Architektura systemu e‑mail
Przepływ od formularza, przez zgodę i idempotentną wysyłkę, aż po zdarzenia webhooków zasilające supresję i higienę list.
Architektura systemu
Pętla higieny listyPozyskiwanie i zgoda
Adres trafia na listę dopiero po potwierdzeniu
Wysyłka
Supresja to bramka przed każdą wysyłką
Zdarzenia webhooków
Dostawca odsyła, co stało się z każdym mailem
Higiena listy
Odbicia i skargi aktualizują listę supresji
Pętla sprzężenia zwrotnego
Zaktualizowana lista supresji (etap 4) wraca do sprawdzenia supresji (etap 2) i blokuje kolejne wysyłki na odbite i skarżące adresy. Tak zdarzenia webhooków utrzymują listę w zdrowiu.
Wszystkie pytania, na które odpowiada poradnik
Przejrzyj pełny spis i skocz prosto do konkretnej odpowiedzi.
Typy maili: transakcyjne vs marketingowe
- Czym różni się mail transakcyjny od marketingowego?
- Dlaczego podział na transakcyjne i marketingowe ma takie znaczenie?
- Jak rozpoznać, którego typu jest dany mail?
- Czego wymagają przepisy dla każdego typu?
- Kiedy używać każdego typu?
- Co z mailami z szarej strefy, które wyglądają jak oba?
- Czy mail o porzuconym koszyku jest transakcyjny czy marketingowy?
- Czy mail powitalny jest transakcyjny czy marketingowy?
- Jakie inne maile bywają często źle klasyfikowane?
- Tabela referencyjna dla najtrudniejszych przypadków
- Jak postąpić z prawdziwą hybrydą, która miesza oba?
- Przykład praktyczny: rozdzielenie zanieczyszczonego potwierdzenia zamówienia
- Jakich maili transakcyjnych faktycznie potrzebuje moja aplikacja?
- Po co mi oddzielne subdomeny dla transakcyjnych i marketingowych?
- Subdomeny, strumienie i pule IP, co właściwie jest rozdzielane?
- Gotowy do skopiowania DNS dla dwóch czystych subdomen wysyłkowych
- Weryfikacja konfiguracji za pomocą dig
- Opcjonalne, ale zalecane: utwardzenie poza SPF/DKIM/DMARC
- Na co zwracać uwagę przy wyborze usługi e‑mail?
- Jak wygląda czysta wysyłka transakcyjna w kodzie?
- Jak wygląda zgodna wysyłka marketingowa w kodzie?
- Jak wygląda lista kontrolna wdrożenia?
- Jakich najczęstszych błędów unikać?
- Co przeczytać dalej?
Jakich maili transakcyjnych potrzebuje Twoja aplikacja?
- Jak korzystać z tego rozdziału?
- Jakich maili transakcyjnych potrzebuje moja aplikacja?
- Czego potrzebuje aplikacja skupiona na uwierzytelnianiu?
- Czego potrzebuje platforma newsletterowa lub treściowa?
- Czego potrzebuje aplikacja e‑commerce lub marketplace?
- Czego potrzebuje usługa SaaS lub subskrypcyjna?
- Czego potrzebuje aplikacja finansowa lub fintech?
- Czego potrzebuje platforma społecznościowa?
- Czego potrzebują narzędzia deweloperskie lub platforma API?
- Czego potrzebuje aplikacja medyczna lub zgodna z HIPAA?
- Jak porównać zestawy niezbędne na pierwszy rzut oka?
- Jak krytyczny jest każdy mail i co to oznacza dla inżynierii?
- Pełny katalog maili
- Maile uwierzytelniania i bezpieczeństwa
- Kiedy i jak wysłać weryfikację e‑maila?
- Co wchodzi w mail z kodem OTP / 2FA?
- Czego potrzebuje mail z resetem hasła?
- Kiedy wysłać alert bezpieczeństwa?
- Maile zarządzania kontem
- Co powinien zawierać mail powitalny?
- Kiedy wysyłać powiadomienia o aktualizacji konta?
- Maile e‑commerce i transakcji
- Co wchodzi w potwierdzenie zamówienia?
- Kiedy wysyłać powiadomienia o wysyłce?
- Czego potrzebuje mail z fakturą lub paragonem?
- Maile subskrypcji i rozliczeń
- Czego potrzebuje potwierdzenie subskrypcji?
- Kiedy wysyłać powiadomienie o odnowieniu subskrypcji?
- Jak obsłużyć powiadomienie o nieudanej płatności?
- Maile powiadomień i aktualizacji
- Kiedy zapowiedź funkcji jest transakcyjna, a nie marketingowa?
- A co z powiadomieniami o aktywności, wzmiankach i podsumowaniach?
- Wymagania przekrojowe dla każdego maila w tym katalogu
- Lista kontrolna wdrożenia
- Co przeczytać dalej?
Dostarczalność
- Dlaczego mój e‑mail trafia do spamu zamiast do skrzynki odbiorczej?
- Dlaczego uwierzytelnianie e‑maili jest teraz nienegocjowalne?
- Czym jest SPF i dlaczego go potrzebuję?
- Czym jest DKIM i czym różni się od SPF?
- Czym jest DMARC i co oznacza „zgodność” (alignment)?
- DMARCbis (RFC 9989): co zmienia najnowszy standard?
- Jak zweryfikować konfigurację SPF, DKIM i DMARC?
- Czym jest reputacja nadawcy i dlaczego ma znaczenie?
- Jak rozgrzać nowe IP lub domenę?
- Jak utrzymać reputację w dobrym stanie, gdy już ją zbuduję?
- Czym jest odrzucenie (bounce) i jak obsługiwać twarde kontra miękkie odrzucenia?
- Czym jest skarga i jaki wskaźnik skarg jest zbyt wysoki?
- Czego dokładnie wymagały zasady dla masowych nadawców Gmail/Yahoo/Microsoft z 2024 roku?
- BIMI: pokazywanie logo w skrzynce odbiorczej
- ARC: przetrwanie przekierowań i list mailingowych
- MTA-STS i TLS-RPT: wymuszanie szyfrowania transportu
- Jak ustrukturyzować domeny i subdomeny wysyłające?
- Jakiego TTL DNS używać dla rekordów e‑mail?
- Moje e‑maile trafiają do spamu: co sprawdzić i w jakiej kolejności?
- Co powinienem przeczytać dalej?
Zarządzanie listą
- Czym jest lista supresji i po co mi ona?
- Które adresy poddawać supresji, a które mogę kiedykolwiek przywrócić?
- Jak przechowywać wpisy supresji w bazie danych?
- Jak sprawdzać supresję przed każdą wysyłką?
- Czym jest higiena list i czym różni się od supresji?
- Jak często uruchamiać każde zadanie czyszczenia?
- Usuwać nieaktywnych subskrybentów czy najpierw próbować ich odzyskać?
- Jak długo przechowywać każdy rodzaj danych e-mail?
- Jak wdrożyć politykę retencji w kodzie?
- Które metryki mówią mi, że lista się psuje?
- Czy listy transakcyjne i marketingowe powinny być osobne?
- Jak wygląda kompletna lista kontrolna zarządzania listą?
- Co przeczytać dalej?
Projektowanie maili transakcyjnych
- Dlaczego maile transakcyjne są tak ważne?
- Jakie są zasady fundamentalne projektowania maili transakcyjnych?
- Jak napisać temat wiadomości?
- Czym jest pre-header i jak go wykorzystać?
- Jak zbudować strukturę treści maila?
- Dlaczego liczy się projekt mobile-first i jak go zrobić?
- Jak uczynić maile transakcyjne dostępnymi?
- Jakie ustawić pola From, Reply-To i nadawcy?
- Jak prezentować kody OTP i linki akcji?
- Jak poprawnie wysłać maila z backendu?
- Jak obsłużyć to, co idzie nie tak?
- Jak przetestować szablon transakcyjny przed wdrożeniem?
- Czy jest jedna checklista do przejrzenia przed wysyłką?
- Co przeczytać dalej?
Pozyskiwanie adresów
- Dlaczego pozyskiwanie to punkt o najwyższej dźwigni w całym systemie
- Jak zwalidować adres e‑mail?
- Jak powinna działać walidacja po stronie klienta?
- Pragmatyczna kontrola po stronie klienta
- Co powinna sprawdzać walidacja po stronie serwera?
- Wzorcowa kontrola MX w Node
- Dlaczego każda kontrola serwerowa istnieje?
- Jak utrzymać wykrywanie domen jednorazowych na bieżąco?
- Jakie są częste błędy walidacji adresu?
- Checklista walidacji
- Czym jest double opt-in?
- Jak wygląda proces double opt-in?
- Jak bezpiecznie generować i weryfikować token?
- Jakie reguły czasowe powinien spełniać krok weryfikacji?
- Kiedy używać single opt-in zamiast double opt-in?
- Tabela decyzyjna, którego użyć
- Dlaczego double opt-in jest wart tarcia?
- Co dzieje się z adresami, które nigdy nie potwierdzają?
- Jak bronić się przed subscription‑bombingiem przez mój formularz?
- Checklista double opt-in
- Jak zaprojektować formularz, który konwertuje?
- Jak powinno zachowywać się pole e‑mail?
- Jak zebrać ważną zgodę marketingową za pomocą checkboxów?
- Jakich dark patterns musi unikać formularz zgody?
- Jakie metadane zgody muszę zebrać i przechowywać?
- Jak rozłożyć formularz?
- Jak zatrzymać boty bez szkodzenia prawdziwym użytkownikom?
- Jakie są częste błędy projektu formularza?
- Checklista projektu formularza
- Jak obsłużyć błędy pozyskiwania i nadużycia?
- Co zrobić, gdy e‑mail jest nieprawidłowy?
- Jak działa sugerowanie literówek
- Co pokazać, gdy e‑mail jest już zarejestrowany?
- Ponowny zapis i przypadek ponownej zgody
- Jak ograniczyć liczbę zgłoszeń (rate limiting), by zatrzymać nadużycia?
- Warstwowy projekt rate limitingu
- Jak po pozyskaniu odróżnić prawdziwe odbicie od sygnału nadużycia?
- Checklista obsługi błędów
- Jak zaprojektować mail weryfikacyjny, w który ludzie naprawdę klikają?
- Częste błędy w całym przepływie pozyskiwania
- Co przeczytać dalej?
Maile marketingowe
- Czym jest mail marketingowy i czym różni się od transakcyjnego?
- Jakich fundamentalnych zasad nigdy nie wolno mi łamać?
- Co liczy się jako ważna zgoda, a co nie?
- Jak łatwy musi być mój wypis?
- Jak pisać tematy, które są otwierane?
- Jak zbudować strukturę maila marketingowego?
- Jak sprawić, by maile działały na mobile?
- Jak segmentować listę?
- Jak personalizować bez wywoływania dyskomfortu?
- Jak często i kiedy wysyłać?
- Jak utrzymać czystą listę?
- Co musi zawierać każdy mail marketingowy?
- Co przeczytać dalej?
Zgodność prawna
- Jak nakładają się na siebie zgodność, dostarczalność i uwierzytelnianie
- Które prawa dotyczą mojego programu e‑mail?
- Czego wymaga CAN‑SPAM w USA?
- Czego wymaga RODO w UE?
- Czego wymaga CASL w Kanadzie?
- A co z Australią, Wielką Brytanią, Brazylią i innymi krajami?
- Jak szybko muszę przetwarzać wypisy i jak długo musi działać link?
- Czy naprawdę potrzebuję nagłówka List-Unsubscribe?
- Jak poprawnie wdrożyć jednoklikowy wypis RFC 8058?
- Czym są wymogi wobec nadawców masowych z lutego 2024 (i maja 2025)?
- Czy centrum preferencji może zastąpić jednoklikowy wypis?
- Jakie rejestry zgód muszę przechowywać?
- Jak długo mogę przechowywać dane subskrybentów?
- Jak obsługiwać żądania osób, których dane dotyczą (dostęp, usunięcie, przenoszenie)?
- Co musi zawierać moja polityka prywatności?
- Jak zachować zgodność przy wysyłce międzynarodowej?
- Co przeczytać dalej?
Niezawodność wysyłki
- Po co e-mailowi w ogóle inżynieria niezawodności?
- Jak mam się upewnić, że nigdy nie wyślę tego samego maila dwa razy?
- Co dokładnie idzie nie tak bez idempotencji?
- Jak działa klucz idempotencji?
- Co dzieje się po stronie serwera, gdy klucz się powtarza?
- Jak powinienem generować klucz?
- Przykład praktyczny: wyprowadzanie stabilnego klucza ze zdarzenia
- Jaki jest częsty błąd idempotencji, którego należy unikać?
- Jak długo klucz idempotencji pozostaje ważny?
- Lista kontrolna idempotencji
- Kiedy powinienem ponowić nieudaną wysyłkę?
- Które błędy są warte ponowienia?
- Dlaczego idempotencja i ponowienia są nierozłączne?
- Jak powinienem rozłożyć ponowienia w czasie?
- Której strategii jitteru powinienem użyć?
- Czy powinienem respektować nagłówek Retry-After?
- Ile razy powinienem ponowić, zanim się poddam?
- Czy ponawiająca strona powinna kiedykolwiek przestać próbować jako flota?
- Lista kontrolna ponawiania
- Jak poprawnie zareagować na każdy rodzaj błędu?
- Kiedy potrzebuję kolejki zamiast wysyłki inline?
- Jak pozostać w ramach rate limitów dostawcy i rozgrzać wysyłkę?
- Co z uwierzytelnianiem, wypisaniem się i regułami dla masowych nadawców?
- Jaki timeout ustawić na wywołaniu API poczty?
- Jak to wszystko składa się razem w jedną wysyłkę?
- Co powinienem przeczytać dalej?
Webhooki i zdarzenia
- Czym jest webhook i po co mojemu systemowi pocztowemu?
- Jakie typy zdarzeń będę otrzymywać?
- Jak poprawnie skonfigurować endpoint webhooka?
- Krok 1: Jak powinien zachowywać się sam endpoint?
- Kluczowy błąd kolejności: weryfikuj, zanim potwierdzisz
- Jaki kod statusu zwracać i kiedy?
- Krok 2: Jak weryfikować podpisy webhooków?
- Co, jeśli mój dostawca nie używa Standard Webhooks?
- Krok 3: Jak zarejestrować URL webhooka?
- Checklista konfiguracji endpointu
- Jak przetwarzać każdy typ zdarzenia?
- Jak obsłużyć odbicie (bounce)?
- Co liczy się jako odbicie twarde, a co jako miękkie?
- Czytaj rozszerzony kod statusu SMTP, nie tylko twarde/miękkie
- Częsty błąd: złe zaszufladkowanie „pełnej skrzynki”
- Jak obsłużyć skargę (complaint)?
- Skargi nadchodzą późno i czasem zanonimizowane
- Jak obsłużyć potwierdzenie dostarczenia?
- Uważaj na dostarczanie poza kolejnością
- Dlaczego mój handler webhooka musi być idempotentny?
- Co się dzieje, gdy mój endpoint zwróci błąd?
- Jak przetestować webhooki przed wdrożeniem na produkcję?
- Czy przechowywać pełną historię webhooków, czy tylko najnowszy status?
- Co przeczytać dalej?