Przewodnik użytkownika AI-Mailer

Wymagania

Przed instalacją upewnij się, że hosting ma PHP 8.1 lub nowszy (zalecane 8.2), MySQL 5.7+ (lub równoważną wersję MariaDB), rozszerzenie PHP sodium (używane do offline'owej weryfikacji licencji) oraz dostęp wychodzący SMTP na porcie wymaganym przez dostawcę poczty (najczęściej 587).

Instalator

Wgraj folder aplikacji na hosting i otwórz w przeglądarce install/index.php. Kreator prowadzi przez cztery kroki:

1. 1
   Sprawdzenie wymagań — potwierdza wersję PHP, wymagane rozszerzenia (w tym sodium) oraz zapisywalność folderów aplikacji tam, gdzie to potrzebne.
2. 2
   Połączenie z bazą danych i prefiks tabel — podajesz host MySQL, nazwę bazy, użytkownika, hasło oraz prefiks tabel (domyślnie aim_). Instalator tworzy wszystkie tabele z dołączonych migracji.
3. 3
   Konto administratora — tworzysz pierwsze konto Super Admina: imię i nazwisko, e-mail i hasło.
4. 4
   Zakończenie — instalator zapisuje config.php i pokazuje link do strony logowania. Usuń folder install/ (albo ogranicz do niego dostęp) po potwierdzeniu, że instalacja działa.

Pierwsze logowanie i licencja

Zaloguj się kontem administratora utworzonym podczas instalacji. Aplikacja działa na poziomie Free, dopóki nie wpiszesz klucza licencji — przejdź do Ustawienia → Licencja (tylko Admin), wklej klucz i zapisz. Klucz jest weryfikowany całkowicie offline, względem domeny, na której aplikacja aktualnie działa, i jego daty wygaśnięcia; żadne dane o Twojej instalacji czy kluczu nigdy nie są nigdzie wysyłane w celu tej weryfikacji. Brakujący, nieprawidłowy albo wygasły klucz nigdy nie blokuje aplikacji — po cichu wraca do poziomu Free. Zobacz Poziomy licencji, żeby sprawdzić, co odblokowuje każdy poziom.

Nadawcy i serwery SMTP

SMTP to protokół, którym jeden serwer pocztowy przekazuje e-mail drugiemu — to realny mechanizm stojący za każdą wysłaną wiadomością. Kliknięcie „wyślij kampanię” nie wysyła e-maila samodzielnie: aplikacja łączy się z serwerem SMTP, który skonfigurowałeś (host, port, szyfrowanie, login i hasło), i to ten serwer faktycznie przekazuje wiadomość dalej.

W zakładce Nadawcy definiujesz nazwę i adres „Od” pokazywany odbiorcom; w Serwery SMTP — faktyczne dane połączenia używane do wysyłki. Kampania nie jest ograniczona do jednego serwera — możesz wybrać kilka aktywnych serwerów, a mechanizm wysyłki rotuje między nimi, przechodząc przez kolejkę odbiorców. Ma to znaczenie, bo każdy dostawca ma własne limity (np. Gmail ogranicza liczbę e-maili dziennie na konto):

• Limit na godzinę i limit na dzień — 0 oznacza brak limitu. Gdy serwer osiągnie swój limit, mechanizm pomija go do końca danego okresu i kontynuuje przez inny serwer z rotacji — odbiorcy nie są oznaczani jako „błąd”, tylko wstrzymani do zwolnienia limitu.
• Przerwa między wysyłkami — pauza w sekundach między wiadomościami wysyłanymi przez dany serwer, przydatna dla dostawców ograniczających tempo, nie tylko dzienną liczbę.
• Kolejność — decyduje, który serwer rotacja próbuje pierwszy wśród wybranych w kampanii; niższe liczby idą pierwsze.

Szablony

Buduj wielokrotnego użytku szablony wiadomości w edytorze kodu (CodeMirror) z podglądem na żywo obok edytowanego HTML/CSS, albo zacznij od jednego z gotowych szablonów i dostosuj go. Większość klientów pocztowych usuwa bloki <style> i całkowicie ignoruje JavaScript, dlatego stylowanie stosowane jest w stylach wbudowanych (inline) — to też czyni renderowanie w Outlooku i innych wymagających klientach przewidywalnym.

Import odbiorców

Odbiorców można dodawać na kilka sposobów, a wszystkie używają tego samego modelu tagów i pól dodatkowych:

• Import CSV/XLSX — Odbiorcy → Importuj automatycznie rozpoznaje nagłówki kolumn po angielsku i po polsku (email/e-mail, first_name/imię, status, tags oraz kolumny pól dodatkowych). Tylko brakujący lub nieprawidłowy e-mail jest twardym błędem wiersza — każdy inny problem jest obsługiwany łagodnie, żeby jeden błędny wiersz nie blokował całego pliku. Po imporcie dostajesz podsumowanie, ile wierszy dodano, zaktualizowano albo pominięto.
• Szybki import — wklej listę adresów bezpośrednio, bez przygotowywania pliku.
• Import Bridge — pobiera odbiorców bezpośrednio z istniejącej, zewnętrznej tabeli MySQL, na przykład tabeli subskrybentów prowadzonej już przez stronę WordPress albo Joomla, albo jakikolwiek inny system z własną bazą MySQL. To ogólne połączenie z bazą danych, nie wtyczka zbudowana pod konkretną platformę: nadajesz nazwę połączeniu, podajesz host/port/bazę/tabelę/dane logowania (hasło jest szyfrowane przed zapisem), testujesz połączenie, mapujesz kolumnę e-mail i nazwę, wybierasz tryb duplikatów i tagi do przypisania, a następnie uruchamiasz most. Każdy odbiorca wprowadzony w ten sposób jest oznaczony informacją, który most go wprowadził, tak samo jak import czy formularz zapisu zapisują swoje własne źródło.
• Tagi — segmentacja działa przez tagi zamiast sztywnych list mailingowych, więc jeden odbiorca może należeć do dowolnej liczby grup.

Tworzenie i wysyłka kampanii

Kampania wybiera szablon, jeden lub więcej nadawców/serwerów SMTP oraz grupę odbiorców według tagu. Cztery różne wyzwalacze napędzają pod maskami dokładnie ten sam mechanizm wysyłki — wybierz ten, który pasuje do Twojego sposobu pracy, albo łącz je między różnymi kampaniami:

Wszystkie cztery finalnie wywołują ten sam mechanizm przetwarzania wsadowego, więc zakolejkowana kampania może być podjęta i kontynuowana przez każdy z nich — wystartowanie wysyłki przez „Wyślij teraz” i zamknięcie karty nie gubi postępu, jeśli skonfigurowany jest też wyzwalacz cron.

Formularze zapisu i podwójna zgoda

Subscribe Widget pozwala zaprojektować osadzalny publiczny formularz zapisu, hostowany w całości na własnej stronie www — aplikacja generuje zwykły, samodzielny <form> ze stylami inline (nie loader <script>), więc działa nawet w kreatorach stron, które usuwają tagi script z wklejanych bloków HTML, i nie ma problemów z CORS, bo przeglądarka wysyła formularz bezpośrednio. Każdy widget ma własną nazwę, opcjonalne pola imienia/nazwiska z własnymi placeholderami, etykietę i kolor przycisku oraz jeden lub więcej tagów przypisywanych automatycznie każdemu, kto się przez niego zapisze. Ekran edycji pokazuje podgląd na żywo i gotowy do skopiowania fragment do osadzenia, wygenerowany od razu przy tworzeniu widgetu:

<form method="post" action="https://twoja-domena.pl/index.php?component=subscribe&action=submit" style="max-width:360px;font-family:sans-serif;">
  <input type="hidden" name="widget" value="twoj-klucz-publiczny-widgetu">
  <div style="position:absolute;left:-9999px;" aria-hidden="true">
    <label>Nie wypełniaj tego pola<input type="text" name="website" tabindex="-1" autocomplete="off"></label>
  </div>
  <input type="email" name="email" placeholder="Twój adres e-mail" required style="width:100%;padding:10px;margin-bottom:8px;border:1px solid #ccc;border-radius:4px;">
  <button type="submit" style="background:#0054a6;color:#fff;border:0;padding:10px 20px;border-radius:4px;cursor:pointer;">Zapisz się</button>
</form>

Ukryte pole website to honeypot — niewidoczne dla prawdziwych odwiedzających, ale atrakcyjne dla prostych botów — a każde zgłoszenie jest dodatkowo sprawdzane względem listy wykluczeń i blokowanych IP, zanim zostanie przyjęte.

Włączenie podwójnej zgody (double opt-in) oznacza, że nowe zgłoszenie nie jest dodawane do listy odbiorców od razu — wysyłany jest e-mail potwierdzający, a adres staje się prawdziwym, oznaczonym tagami odbiorcą dopiero po kliknięciu tego linku. Wymaga to aktywnego serwera SMTP, więc checkbox jest zablokowany (z wyjaśnieniem), jeśli żaden serwer nie jest jeszcze skonfigurowany.

Odczytywanie statystyk

Śledzenie otwarć i kliknięć działa przez przepisanie treści e-maila w momencie wysyłki — niewidoczny piksel śledzący 1×1 dla otwarć i zamiana każdego linku na adres przekierowujący dla kliknięć, oba kontrolowane checkboxami śledzenia na formularzu kampanii. Piksel odpala się tylko, jeśli klient pocztowy odbiorcy faktycznie wczytuje zdalne obrazy, więc prawdziwy wskaźnik otwarć jest zawsze trochę wyższy niż zmierzony — to fundamentalne ograniczenie śledzenia opartego na pikselu, powszechne w całej branży, nie coś specyficznego dla tej aplikacji. Śledzenie kliknięć jest bardziej wiarygodne, bo odpala się tylko, gdy odbiorca celowo kliknie.

Szczegóły otwarć/kliknięć per odbiorca są widoczne na stronie szczegółów samej kampanii, a zagregowane wskaźniki — wysyłki dziennie, wg tagu, wg kampanii, mapa geograficzna, rozbicie po urządzeniach/przeglądarkach — pojawiają się w panelu Statystyki.

Lista wykluczeń i blokowane IP

Czarna lista ma dwie niezależne zakładki, które łatwo pomylić:

• Lista wykluczeń — adresy e-mail i domeny, które nigdy nie mają otrzymać kampanii, niezależnie od tagów. Dodaj konkretny adres albo całą domenę za pomocą wzorca z gwiazdką (np. *@example.com). Jest to sprawdzane zarówno przy starcie kampanii, jak i ponownie w momencie faktycznej wysyłki każdej wiadomości, więc dodanie adresu tutaj zatrzymuje przyszłe wysyłki nawet do już zakolejkowanej kampanii.
• Blokowane IP — całkowicie osobna lista adresów IP (albo wzorców), którym blokuje się zgłaszanie przez publiczny formularz zapisu. To ochrona przed nadużyciami widgetu, niezwiązana z tym, kto może otrzymać kampanię.

Obie zakładki wspierają masowe dodawanie wielu wpisów naraz przez pole tekstowe, i obie używają prostego dopasowania z gwiazdką (*), nie wyrażeń regularnych.

DKIM/SPF/DMARC i obsługa odbić

SPF, DKIM i DMARC to trzy niezależne, uzupełniające się mechanizmy, które mówią odbierającemu serwerowi pocztowemu, że wiadomość naprawdę pochodzi od Ciebie, a nie od kogoś, kto podszywa się pod Twoją domenę. Razem odpowiadają za dużą część tego, czy wiadomość trafia do skrzynki, czy do spamu.

SPF i DKIM warto skonfigurować dla każdej domeny, z której wysyłasz kampanie — bez nich część odbiorców (szczególnie Gmail i Outlook) coraz częściej kieruje wiadomości prosto do spamu. DMARC jest krokiem dodatkowym, przydatnym, gdy SPF i DKIM już działają.

Odbicie (bounce) to informacja o odrzuceniu wysyłana z powrotem przez serwer odbierający — adres nie istnieje, skrzynka jest pełna itd. Żeby to wykryć, aplikacja musi sprawdzać prawdziwą skrzynkę, na którą trafiają zwroty — dlatego obsługa odbić wymaga własnych danych logowania, innych niż te do wysyłki. Na zakładce Odbicia przy serwerze SMTP: włącz sprawdzanie, wpisz host/port/protokół (IMAP albo POP3) i folder tej skrzynki, podaj login i hasło (zupełnie inne konto niż login SMTP, zwykle coś jak bounce@twojadomena.pl) oraz ustaw częstotliwość sprawdzania. Wykryte trwałe odbicie ustawia status odbiorcy na „odbity” globalnie, we wszystkich tagach, więc kolejne kampanie automatycznie go pomijają.

Poziomy licencji

AI-Mailer działa na trzech poziomach licencji — Free, Basic i Full. Każdy poziom pozwala wysyłać prawdziwe kampanie do prawdziwych odbiorców przez własne serwery SMTP; płatne poziomy dodają do tego zestaw dodatków związanych z dostarczalnością, raportowaniem i automatyzacją. Klucz licencji jest sprawdzany całkowicie offline — żadne dane o instalacji czy kluczu nigdzie nie są wysyłane.

Dostępne na każdym poziomie

Nieograniczona liczba kampanii, odbiorców, tagów i szablonów; wysyłka SMTP przez własny serwer (serwery); wizualny kreator szablonów i edytor kodu; widgety zapisu, łącznie z mailami potwierdzającymi double opt-in; oraz postęp wysyłki per kampania, śledzenie otwarć/kliknięć i raportowanie „Wysyłki dziennie” / „Wg tagu” / „Wg kampanii” na stronie Statystyk.

Co dodają Basic i Full

Basic i Full odblokowują dokładnie ten sam zestaw funkcji opisany powyżej — w samej aplikacji nie ma między nimi różnicy funkcjonalnej. Różnica jest wyłącznie w liczbie odrębnych domen objętych jednym kluczem: klucz Basic jest związany z jedną domeną, a klucz Full obejmuje do 25 domen. Wybierz ten, który odpowiada liczbie stron, na których planujesz uruchomić AI-Mailer.

Zakup lub aktualizację licencji znajdziesz na shop.creativai.ai.

Wymagania systemowe

• PHP 8.1 lub nowszy (zalecane 8.2)
• MySQL 5.7+ lub równoważna wersja MariaDB
• Rozszerzenie PHP sodium (offline'owa weryfikacja licencji Ed25519)
• Dostęp wychodzący SMTP z hostingu na porcie wymaganym przez dostawcę
• Dostęp IMAP lub POP3 do skrzynki na odbicia, jeśli potrzebna jest automatyczna obsługa odbić

Struktura folderów dla self-hostingu

AI-Mailer jest dostarczany jako pojedynczy folder, który wgrywasz do dowolnego podfolderu hostingu — nie ma niczego do przenoszenia poza webroot. Ochrona wrażliwych plików (config.php, migracje, logi) jest realizowana przez reguły .htaccess dołączone obok nich, a nie przez poleganie na specjalnym układzie serwera.