Przejdź do głównej zawartości

Wysyłka maili masowych (Mailing)

Przewodnik po module do rozsyłania wiadomości i newsletterów do klientów.

👤 Instrukcja dla pracownika (Marketing / Administracja)​

Moduł "Mailing" umożliwia masową komunikację e-mail z wybranymi grupami klientów. Właściwe wykorzystanie modułu wymaga zrozumienia mechanizmów zgód marketingowych oraz segmentacji bazy.

1. Zgody marketingowe (Zgodność z RODO)​

Przed realizacją jakiejkolwiek kampanii należy upewnić się, że spełnione są wymogi prawne. Podczas rejestracji konta użytkownicy w sposób dobrowolny określają swoje preferencje dotyczące komunikacji marketingowej. Ścieżka dla pracownika: Dashboard ➔ Mailing ➔ Zgody

  • System AcePark automatyzuje weryfikację zgód. Wiadomości o charakterze promocyjnym dystrybuowane są wyłącznie do profili posiadających aktywną zgodę marketingową. System automatycznie blokuje wysyłkę do osób, które zrezygnowały z subskrypcji.
  • W przypadku zgłoszenia od klienta w recepcji z prośbą o zaprzestanie wysyłki wiadomości marketingowych, należy odnaleźć jego profil w zakładce Zgody i dokonać dezaktywacji odpowiedniego przełącznika.

2. Segmenty (Zarządzanie bazą odbiorców)​

W celu optymalizacji procesu docierania do wybranych grup docelowych (np. "wszyscy klienci z Opola uczęszczający na zajęcia we wtorki"), system wykorzystuje Segmenty. Ścieżka dla pracownika: Dashboard ➔ Mailing ➔ Segmenty ➔ Nowy segment

  • Segment to dynamicznie aktualizowana lista odbiorców, spełniających zdefiniowane kryteria filtrujące (np. "Aktywni Klienci - Legionowo").
  • Tworzenie segmentu polega na wyborze parametrów: lokalizacji, konkretnych grup zajęciowych oraz statusu aktywności konta.
  • Główną zaletą segmentów jest ich autouzupełnianie. Każdy nowy użytkownik, który spełni zapisane kryteria (np. nowa osoba dołączająca do grupy w Legionowie), zostanie automatycznie włączony do segmentu, bez konieczności manualnej aktualizacji bazy.

3. Tworzenie i realizacja kampanii​

Moduł służący do konfiguracji oraz dystrybucji wiadomości. Ścieżka dla pracownika: Dashboard ➔ Mailing ➔ Kampanie ➔ Nowa kampania

  • Nazwa kampanii: Wewnętrzny identyfikator systemowy (niewidoczny dla klientów), ułatwiający archiwizację (np. "Oferta wakacyjna - Wiosna 2026").
  • Temat wiadomości: Oficjalny temat e-maila wyświetlany w skrzynkach odbiorczych klientów (np. "Ruszyły zapisy na Półkolonie!").
  • Odbiorcy: Możliwość wskazania wcześniej utworzonego Segmentu lub ręczny wybór pojedynczych adresów.
  • Treść (HTML): W systemie dostępny jest wbudowany, wizualny edytor tekstu umożliwiający formatowanie wiadomości, wstawianie grafik oraz linków.
  • Weryfikacja: Przed finalną wysyłką zaleca się przeprowadzenie testu poprzez funkcję "Wyślij test", co pozwala na sprawdzenie poprawności formatowania wiadomości na urządzeniach mobilnych.
  • Wysyłka: Po zapisaniu wersji roboczej i finalnej weryfikacji należy użyć przycisku "Wyślij". Uwaga: Wysyłka jest procesem nieodwracalnym i realizowanym bezzwłocznie.

4. Statystyki​

Po zrealizowaniu kampanii, moduł zapewnia dostęp do wskaźników efektywności (przycisk Statystyki obok nazwy kampanii), prezentujących m.in.:

  • Wskaźnik dostarczalności (procent wiadomości pomyślnie odebranych).
  • Wskaźnik otwarć (Open Rate) – odsetek odbiorców, którzy wyświetlili treść e-maila.
  • Ewentualne błędy doręczenia (np. wynikające z usuniętych lub błędnych adresów e-mail).
  • Wskaźnik klikalności (CTR) – liczba użytkowników, którzy kliknęli w linki umieszczone w treści wiadomości.
  • Wskaźnik rezygnacji (Unsubscribe Rate) – liczba osób, które wypisały się z bazy po otrzymaniu wiadomości.

🛠️ Dokumentacja techniczna​

Informacje dla programistów integrujących bazę wysyłkową.

Komunikacja z SendGrid​

Moduł mailingu oparty jest o providera SendGrid (lub podobne rozwiązanie dostarczające API i webhooks).

  • Otwarcia i kliknięcia: Tabela statystyk nasłuchuje na webhooks ze statusami dostarczenia wiadomości od dostawcy mailowego. Opóźnienie statystyk wynika ze specyfiki działania webhooków.
  • Wypisania: Kliknięcie przez klienta przycisku "Wypisz się" z maila powinno automatycznie trafiać na webhook i aktualizować wpis w tabeli powiązanej z danym userEmail, blokując flagę w ustawieniach (tabela zgód consents).
  • Idempotentność i zablokowane adresy: Osoby wypisane nigdy nie dostają wiersza w pętli wysyłkowej, nawet jeżeli znajdują się w Segmencie z odznaczonym parametrem Wymagaj zgody marketingowej. Hard opt-out w tabeli zawsze nadpisuje wybrane grupy docelowe.

Wyznaczanie listy odbiorców​

Cała logika wyboru odbiorców (lib/actions/mail-campaigns.ts) rozstrzygana jest po stronie D1 — worker nigdy nie ładuje pełnych tabel do pamięci, dzięki czemu zużycie pamięci nie rośnie wraz z bazą klientów.

  • Jedno zapytanie zamiast łączenia w JS: kandydaci pochodzą z tabeli player, a zgody (user.marketingConsent / marketingConsentElectronic) i wypisania (client_mail_preferences.unsubscribed_at) dołączane są przez LEFT JOIN. Warunki zgody i wypisania trafiają do HAVING, deduplikacja adresów do GROUP BY lower(trim(owner_email)).
  • Paginacja kursorowa: odbiorcy pobierani są stronami po RECIPIENT_PAGE_SIZE (500) z kursorem lower(trim(owner_email)) > ?. Każda strona jest kolejno: uzupełniana o tokeny wypisu, wysyłana do SendGrid i logowana w mail_campaign_recipient — w pamięci znajduje się zawsze najwyżej jedna strona.
  • Podgląd odbiorców: previewRecipients zwraca liczniki policzone agregatem SQL oraz próbkę pierwszych PREVIEW_SAMPLE_SIZE (50) adresów, a nie pełną listę.
  • Listy ręczne: adresy wskazane ręcznie (manual_include / „konkretni klienci") pomijają bramkę zgody, ale nadal respektują wypisanie. Są rozwiązywane osobno i wykluczane z zapytania filtrowego (NOT IN (SELECT value FROM json_each(?))), więc nikt nie trafia na listę dwa razy. Listy przekazywane są jako pojedynczy parametr JSON, co omija limit parametrów bindowanych w D1.