Mail Pilot

Mail Pilot zastępuje domyślną funkcję pocztową WordPressa serwisem pocztą transakcyjną Brevo. Kieruje każdą wychodzącą wiadomość przez API HTTP Brevo (z automatycznym fallbackiem do SMTP), zapisuje każde wysłanie w przeszukiwalnym logu i w czasie rzeczywistym weryfikuje doręczenia przez webhooki. Efekt: niezawodna poczta transakcyjna i pełna widoczność tego, co Twoja strona faktycznie doręcza.

Wtyczka jest stworzona dla właścicieli i administratorów stron, którzy muszą mieć pewność, że resety haseł, potwierdzenia zamówień, odpowiedzi z formularzy kontaktowych, powiadomienia WooCommerce i inne maile systemowe trafiają do skrzynki. Nie dodaje funkcji marketingowych ani kampanii: skupia się na warstwie transakcyjnej WordPressa.

Wyróżniki

• Wysyłka przez API Brevo. Wszystkie wywołania wp_mail() idą przez API transakcyjne Brevo, co poprawia dostarczalność względem domyślnej funkcji mail() w PHP.
• Automatyczny fallback do SMTP. Jeśli wywołanie API nie powiedzie się (na przykład przez chwilowy problem sieciowy), wiadomość jest ponowiona przez Brevo SMTP, by poczta się nie zgubiła.
• Przeszukiwalny log mailowy. Każda wychodząca wiadomość jest zapisywana z odbiorcą, tematem, treścią, nagłówkami, statusem i znacznikiem czasu. Log da się filtrować po statusie i przeszukiwać po odbiorcy albo temacie.
• Śledzenie otwarć i kliknięć. Po włączeniu Brevo wstrzykuje piksel śledzący i przepisuje linki, dzięki czemu wtyczka rejestruje otwarcia i kliknięcia każdej wiadomości.
• Weryfikacja doręczenia przez webhooki. Brevo odsyła zdarzenia delivered, hard bounce, soft bounce, blocked, deferred i spam complaint, które Mail Pilot odzwierciedla we wpisie logu.
• Automatyczne czyszczenie. Zaplanowane zadanie WP-Cron usuwa stare wiersze logu zgodnie z konfigurowalnym okresem retencji, dzięki czemu baza nie rośnie w nieskończoność.
• Zapobieganie konfliktom. Mail Pilot wykrywa inne wtyczki SMTP (w szczególności WP Mail SMTP) i ostrzega, gdyby obie nadpisywały wp_mail(), zapobiegając zduplikowanym lub zgubionym wiadomościom.
• Ponowne wysłanie i test. Każdą zalogowaną wiadomość można wysłać ponownie z poziomu panelu admina, a wbudowane narzędzie testowego maila weryfikuje konfigurację.

Wymagania

• WordPress 6.0 lub nowszy.
• PHP 7.4 lub nowszy (rekomendowane PHP 8.1+).
• Konto Brevo (darmowy plan wystarcza dla typowych wolumenów transakcyjnych).
• Zweryfikowany adres nadawcy albo uwierzytelniona domena nadawcza w Brevo.
• Wychodzące HTTPS z serwera WordPress do api.brevo.com na porcie 443 oraz port 587 dla fallbacka SMTP.
• Włączony WordPress cron (wp-cron) albo systemowy cron uderzający w wp-cron.php, żeby zadanie czyszczenia odpalało się o czasie.

Instalacja

1. Pobierz najnowszy mail-pilot.zip z konta albo ze strony pobierania wtyczki.
2. W panelu WordPressa otwórz Wtyczki → Dodaj nową → Wyślij wtyczkę.
3. Wybierz plik ZIP, kliknij Zainstaluj teraz, a potem Włącz wtyczkę.
4. Po aktywacji pojawia się nowy wpis pod Mail Pilot → Ustawienia. Wtyczka dodaje też menu najwyższego poziomu Mail Pilot, które daje bezpośredni dostęp do ekranów logu i statystyk.

Przy aktywacji Mail Pilot tworzy swoją własną tabelę w bazie ({prefix}_mail_pilot_logs) na log mailowy. Żaden e-mail nie jest przechwytywany, dopóki nie zapiszesz klucza API i nie włączysz integracji.

Konfiguracja

Konfiguracja dzieli się na trzy obszary: dane uwierzytelniające Brevo, tożsamość nadawcy oraz opcje operacyjne logowania, śledzenia i retencji. Wszystkie ustawienia są pod Mail Pilot → Ustawienia.

1. Załóż konto Brevo i klucz API

1. Zarejestruj się na brevo.com , jeśli jeszcze nie masz konta. Darmowy plan pozwala na hojny dzienny wolumen poczty transakcyjnej, co wystarcza większości małych i średnich stron.
2. Zaloguj się do panelu Brevo.
3. Otwórz menu użytkownika w prawym górnym rogu i wybierz SMTP & API.
4. Przejdź do zakładki API Keys i kliknij Generate a new API key.
5. Nadaj kluczowi rozpoznawalną nazwę (na przykład wordpress-mail-pilot) i skopiuj wygenerowaną wartość. Brevo pokazuje sekret tylko raz; zachowaj go w bezpiecznym miejscu.

2. Zweryfikuj nadawcę

Brevo nie wysyła wiadomości od niezweryfikowanego nadawcy. Zanim zapiszesz konfigurację w WordPressie, upewnij się, że albo sam adres nadawcy, albo cała domena są zweryfikowane w Brevo:

• Dla pojedynczego adresu otwórz w Brevo Senders, Domains & Dedicated IPs → Senders, dodaj adres i potwierdź go mailem, który wyśle Brevo.
• Dla domeny otwórz Senders, Domains & Dedicated IPs → Domains i przejdź przez kreator, który prosi o dodanie rekordów DNS SPF, DKIM i DMARC. Uwierzytelnienie domeny daje najlepszą dostarczalność i jest zdecydowanie zalecane dla stron produkcyjnych.

3. Wpisz dane uwierzytelniające w WordPressie

1. Otwórz Mail Pilot → Ustawienia w panelu WordPressa. Strona dzieli się na trzy zakładki — Ogólne, Logowanie i Zaawansowane — ale dane uwierzytelniające i mailer testowy są w zakładce Ogólne.
2. (Opcjonalnie) W karcie Licencja u góry wklej klucz PILOT-XXXX-XXXX-XXXX-XXXX i wciśnij Zweryfikuj i zapisz, by włączyć automatyczne aktualizacje wtyczki z kanału release na GitHubie.
3. W karcie Połączenie zostaw Mail Provider na Brevo (jedyny obecnie wspierany dostawca).
4. W karcie Brevo Settings wklej klucz API do pola API Key i wciśnij Testuj połączenie, żeby zwalidować dane wobec API Brevo.
5. W karcie Sender ustaw:
   • From Email na zweryfikowany adres z poprzedniego kroku i zaznacz Force From Email, by nadpisać nadawcę ustawianego per wiadomość przez inne wtyczki.
   • From Name na etykietę, która ma występować jako autor wychodzących wiadomości, i zaznacz Force From Name, by wygrywała też z nadpisaniami per wiadomość.
6. Kliknij Zapisz ustawienia.

Jeśli chcesz szybko wysłać maila weryfikacyjnego, karta Test Email na dole zakładki Ogólne udostępnia pole Send To i przycisk Send Test.

4. Wyślij testowy e-mail

Poniżej sekcji z danymi uwierzytelniającymi formularz Wyślij testowy e-mail pozwala zweryfikować całą konfigurację od początku do końca:

1. Wpisz adres docelowy (Twoja własna skrzynka to dobry wybór).
2. Kliknij Wyślij testowy e-mail.
3. Wtyczka od razu pokazuje komunikat o sukcesie lub błędzie, a wiadomość pojawia się w logu w ciągu kilku sekund.

Jeśli wiadomość testowa trafia do skrzynki, integracja API działa. Jeśli nie dotrze w ciągu paru minut, otwórz wpis w logu i sprawdź szczegóły odpowiedzi zwrócone przez Brevo, a potem zerknij do sekcji Rozwiązywanie problemów poniżej.

5. Skonfiguruj webhook dostarczeń

Zdarzenia otwarcia, kliknięcia i dostarczenia są pchane z powrotem do WordPressa przez Brevo webhookiem. Ustawienie go jest opcjonalne, ale zalecane — bez niego log pokaże jedynie, że wiadomość została przyjęta przez Brevo, ale nie czy została faktycznie dostarczona, odbita czy otwarta.

1. W Mail Pilocie skopiuj Webhook URL pokazany na stronie ustawień. Wskazuje on endpoint REST https://<twoja-strona>/wp-json/mail-pilot/v1/webhook.
2. W panelu Brevo otwórz Transactional → Settings → Webhook i kliknij Add a new webhook.
3. Wklej URL w pole URL to call.
4. Wybierz zdarzenia do raportowania. Zalecany zestaw to:
   • Sent
   • Delivered
   • Hard bounce
   • Soft bounce
   • Blocked
   • Spam (complaint)
   • Opened (tylko jeśli włączone śledzenie otwarć)
   • Clicked (tylko jeśli włączone śledzenie kliknięć)
5. Zapisz webhook.

Brevo zacznie od razu wysyłać aktualizacje statusu do WordPressa. Tabela logu odświeża kolumnę statusu w miarę napływania zdarzeń.

6. Śledzenie, retencja i czyszczenie

Zakładki Logowanie i Zaawansowane na stronie ustawień wystawiają opcje operacyjne:

• Włącz śledzenie otwarć. Po włączeniu Brevo osadza piksel śledzący 1×1 w ciele HTML. Piksel ładuje klient pocztowy odbiorcy, co liczy się jako otwarcie.
• Włącz śledzenie kliknięć. Po włączeniu linki w mailach HTML są przepisywane na redirector Brevo, który rejestruje kliknięcie, a potem przekierowuje użytkownika do oryginalnego URL-a.
• Retencja logu (dni). Liczba dni, po których wpisy logu są usuwane przez zadanie czyszczące. Domyślnie 30 dni. Ustaw 0, by trzymać wpisy w nieskończoność (niezalecane na ruchliwych stronach).
• Harmonogram czyszczenia. Częstość zdarzenia WP-Cron, które przycina log. Domyślnie codziennie.
• Loguj treść wiadomości. Gdy wyłączone, zapisywane są tylko metadane (odbiorca, temat, status), co zmniejsza rozmiar bazy i unika trzymania treści wrażliwych maili, takich jak resety haseł.

Kliknij Zapisz zmiany, by zatwierdzić.

Użytkowanie

Po włączeniu integracji Mail Pilot działa przezroczyście. Każde wywołanie wp_mail() wykonywane przez rdzeń WordPressa, motywy lub wtyczki jest przechwytywane i przekierowywane przez Brevo. Żadna zmiana w kodzie WooCommerce, Contact Form 7, WPForms, BuddyPress ani innej wtyczki korzystającej ze standardowego API pocztowego WordPressa nie jest wymagana.

Dashboard

Menu najwyższego poziomu Mail Pilot otwiera dashboard, który podsumowuje aktywność pocztową w wybranym okresie. Selektor zakresu u góry przełącza między 7 dni, 14 dni i 30 dni, a sześć kart KPI na górze strony raportuje Łącznie wysłane, Dostarczone (z procentem dostarczalności), Nieudane (z procentem porażek), Odbite, Otwarcia (z procentem otwarć) i Kliknięcia. Liczby aktualizują się w miarę napływania zdarzeń z webhooka.

Pod KPI dashboard renderuje pięć żywych wykresów zasilanych własnym logiem wtyczki:

• Email Volume — dzienny wykres warstwowy wiadomości dostarczonych, zablokowanych i odbitych.
• Delivery Status — pączek z rozbiciem tych samych trzech koszyków w wybranym okresie.
• Opens & Clicks — dzienny wykres liniowy unikalnych otwarć i kliknięć.
• Top Sources — poziomy wykres słupkowy wtyczek/motywów generujących najwięcej maili, wyciągany z miejsca wywołania rejestrowanego przy każdej wysyłce.
• Sending Hours — godzinny histogram pokazujący, kiedy maile wychodzą ze strony i kiedy Brevo je rozsyła; przydatny do wychwytywania burz cronowych.

Karta Brevo Account na dole zaciąga żywy status Twojego konta Brevo: podpięty adres konta, bieżące saldo kredytów i liczniki Requests, Delivered, Opens, Clicks, Hard bounces, Soft bounces, Blocked i Spam reports ze wszystkich kanałów wysyłki (API, relay SMTP i oprogramowanie zewnętrzne).

Log mailowy

Ekran Log mailowy (Mail Pilot → Log mailowy) pokazuje każdą wiadomość obsłużoną przez wtyczkę, od najnowszej, z listą akcji zbiorczych, filtrem statusu, polem wyszukiwania tekstowego i akcją Podgląd per wiersz. Każdy wiersz pokazuje:

• Adres odbiorcy (lub pierwszy adres, jeśli jest ich kilka).
• Temat.
• Bieżący status: queued, sent, delivered, opened, clicked, soft-bounce, hard-bounce, blocked, spam albo error.
• Znacznik czasu ostatniej zmiany statusu.
• ID wiadomości w Brevo (do korelowania wpisu z logami po stronie Brevo).

Pole wyszukiwania nad tabelą służy do filtrowania po odbiorcy albo temacie, a lista statusów — do pokazania tylko nieudanych wiadomości. Kliknięcie w wiersz otwiera widok szczegółowy, który wystawia:

• Pełne nagłówki i treść wiadomości (jeśli logowanie treści jest włączone).
• Listę odbiorców (To, Cc, Bcc).
• Każde śledzone zdarzenie z jego znacznikiem czasu.
• Surową odpowiedź Brevo, przydatną przy zgłoszeniach do wsparcia.

Z widoku szczegółowego możesz kliknąć Wyślij ponownie, by powtórzyć wiadomość bez zmian, albo Kopiuj, by użyć jej jako punktu wyjścia do nowej wiadomości testowej.

Widget na dashboardzie WordPressa

Mail Pilot rejestruje widget na standardowym ekranie Kokpit (stronie, którą WordPress otwiera po zalogowaniu). Widget odzwierciedla własny dashboard wtyczki na pierwszy rzut oka, dzięki czemu wyłapiesz anomalie dostarczania bez klikania w menu Mail Pilot.

Widget wystawia selektor zakresu Ostatnie 7 / 14 / 30 dni, wykres liniowy Email Volume (Dostarczone / Nieudane / Odbite) i stopkę Brevo z bieżącym saldem kredytów oraz licznikami Requests, Delivered, Failed, Bounced, Opens i Clicks. Link Pokaż pełny log w nagłówku otwiera stronę Logu mailowego.

Widget jest opt-in: włączysz go lub wyłączysz pod Mail Pilot → Ustawienia → Zaawansowane → Widget kokpitu.

Praca z innymi wtyczkami

Mail Pilot zastępuje domyślną implementację wp_mail() własnym rozszerzeniem PHPMailera. W konsekwencji jest niekompatybilny z innymi wtyczkami, które robią to samo, w tym z WP Mail SMTP, Easy WP SMTP, Post SMTP, FluentSMTP i podobnymi. Wtyczka wykrywa te najpopularniejsze i pokazuje powiadomienie administracyjne z prośbą o wybór jednego mailera. Zalecana ścieżka: dezaktywuj drugą wtyczkę SMTP i — jeśli trzeba — zaimportuj jej dane uwierzytelniające do Mail Pilota.

WooCommerce, BuddyPress, WPForms, Contact Form 7, Easy Digital Downloads i podstawowe powiadomienia WordPressa działają bez żadnej zmiany: wszystkie idą przez wp_mail() i są tym samym automatycznie przechwytywane przez Mail Pilot.

FAQ

Czy Mail Pilot zastępuje tylko pocztę transakcyjną, czy też kampanie marketingowe? Obsługuje wyłącznie pocztę transakcyjną, czyli wszystko, co idzie przez wp_mail() w WordPressie. Kampaniami marketingowymi tworzonymi w panelu Brevo zarządzasz tam i nie są one widoczne w logu Mail Pilota.

Czy muszę płacić za Brevo? Nie. Darmowy plan Brevo obecnie obejmuje dzienny limit poczty transakcyjnej, który pokrywa potrzeby większości małych i średnich stron. Gdy wolumen urośnie, możesz przejść na płatny plan z poziomu panelu Brevo bez ponownej instalacji wtyczki.

Czy mogę używać WP Mail SMTP i Mail Pilota jednocześnie? Nie. Tylko jedna wtyczka może nadpisywać wp_mail(); uruchomienie dwóch naraz prowadzi do duplikatów, zgubionych wiadomości albo błędów PHP. Dezaktywuj drugą wtyczkę SMTP przed włączeniem Mail Pilota.

Czy treści wiadomości są trzymane w bazie? Tylko jeśli Loguj treść wiadomości jest włączone w ustawieniach. Z wyłączoną opcją log trzyma odbiorcę, temat, nagłówki i status, ale nie treść — co bywa lepsze na stronach wysyłających resety haseł albo inne wrażliwe treści.

Czy śledzenie otwarć zadziała we wszystkich klientach pocztowych? Śledzenie otwarć zależy od tego, czy odbiorca załaduje obrazki zdalne w kliencie pocztowym. Wielu klientów korporacyjnych oraz Apple Mail Privacy Protection blokuje albo pre-fetchuje piksel, więc współczynnik otwarć należy interpretować jako dolną (albo górną) granicę, nie dokładną liczbę.

Czy wtyczka wspiera wielu nadawców? Domyślny nadawca konfigurowany jest globalnie. Wtyczki lub kod przekazujące jawny nagłówek From: do wp_mail() użyją tego adresu, o ile jest zweryfikowany w Brevo. Adresy niezweryfikowane są odrzucane przez API.

Czy mogę wyeksportować log? Tak. Na ekranie logu jest przycisk Eksport CSV, który eksportuje aktualnie filtrowany widok. Eksport zawiera odbiorcę, temat, status, znaczniki czasu i ID wiadomości w Brevo.

Gdzie trzymane są dane? Logi są w niestandardowej tabeli o nazwie {prefix}_mail_pilot_logs w bazie danych WordPressa. Ustawienia leżą w standardowej tabeli opcji WordPressa. Nic nie jest wysyłane do stron trzecich poza samym Brevo.

Czy Mail Pilot jest kompatybilny z multisite? Tak. Każda strona w sieci multisite trzyma własne ustawienia i tabelę logu i używa własnego klucza API Brevo. Wtyczkę da się też aktywować sieciowo.

Rozwiązywanie problemów

Strona ustawień pokazuje „API key rejected”. Skopiuj klucz z Brevo ponownie, upewniając się, że nie ma początkowych ani końcowych spacji. Sprawdź, czy klucz nie został unieważniony albo ograniczony w panelu Brevo. Klucze utworzone dla API v2 mogą nie działać; wygeneruj klucz v3 z zakładki API Keys.

Maile testowe są raportowane jako wysłane, ale nie docierają. Otwórz wpis logu dla testowej wiadomości i sprawdź sekcje Status i Brevo response. Najczęstsze przypadki:

• Odbiorca jest na liście supresji Brevo (wcześniejszy bounce albo rezygnacja z subskrypcji). Usuń adres z Contacts → Suppressed contacts w Brevo.
• Nadawca albo domena nadawcza nie są zweryfikowane, więc Brevo przyjmuje żądanie, ale blokuje wiadomość.
• Dostawca poczty odbiorcy oznaczył wiadomość jako spam. Sprawdź folder ze spamem i zweryfikuj SPF, DKIM oraz DMARC dla domeny nadawczej.

Zdarzenia z webhooka nigdy nie trafiają do logu. Sprawdź, czy URL webhooka zapisany w Brevo zgadza się z tym pokazanym na stronie ustawień Mail Pilota, włącznie z protokołem (https) i ewentualnym podkatalogiem instalacji. WordPress musi być osiągalny z publicznego internetu; webhooki nie dotrą do strony za VPN-em ani do localhost. Jeśli używasz wtyczki bezpieczeństwa albo WAF-a, upewnij się, że żądania do /wp-json/mail-pilot/v1/webhook nie są blokowane.

Stare wpisy logu nie są kasowane. Czyszczenie odpala WordPress cron. Jeśli strona ma bardzo niski ruch, cron może nie odpalać się wystarczająco często; ustaw systemowe zadanie cron wywołujące wp-cron.php co godzinę. Ręczne czyszczenie odpalisz też przyciskiem Uruchom czyszczenie teraz na dole strony ustawień.

E-maile konkretnej wtyczki nie idą przez Brevo. Sprawdź, czy ta wtyczka nie wysyła poczty własną implementacją SMTP zamiast wp_mail(). Wtyczek omijających wp_mail() nie da się przechwycić; zajrzyj do ich dokumentacji, by skierować je na te same dane uwierzytelniające Brevo, albo wyłącz ich własny mailer.

Po przełączeniu na Mail Pilota e-maile zaczęły przychodzić z innego adresu. Adres nadawcy skonfigurowany w Mail Pilocie nadpisuje ten, którego użyłby WordPress. Aby zachować adres „From” per wtyczka, upewnij się, że ta wtyczka jawnie ustawia nagłówek From: przy wywołaniu wp_mail(); w przeciwnym razie zaktualizuj globalnego nadawcę w Mail Pilot → Ustawienia na pożądaną wartość.