Konfiguracja oraz uruchomienie phpList

phplist [ 1 ] to oprogramowanie pozwalające na tworzenie kampanii mailowych dla zdefiniowanych grup użytkowników (adresów email). Owe kampanie mailowe można wysyłać zgodnie z zadanym harmonogramem, tak aby serwery pocztowe rozsyłały maile w godzinach najmniejszego obciążenia.

Instalacja

Z wykorzystaniem własnego repozytroium pakietów należy zainstalować:

pkg install -Uy mail/phplist print/fpdf

Biblioteka print/fpdf jest wykorzystywana przez phplist (poprzez plik konfiguracyjny).

Konfiguracja

Konfiguracja jest rozrzucona w dwa miejsca:

plik konfiguracyjny config_extended.php traktowany jako ustawienia domyślne
plik konfiguracyjny config.php: ustawienia własne oraz nadpisanie ustawień domyślnych
(zdecydowana większość) przechowywana w bazie danych mySQL w tabeli config (z ewentualnych prefixem)

Utworzenie bazy danych

Przed przystąpieniem do pierwszego uruchomienia potrzebna jest baza danych:

CREATE TABLE phplistdb;
CREATE USER 'phplistuser'@'localhost' IDENTIFIED BY '*********';
GRANT ALL ON phplistdb.* TO 'phplistuser'@'localhost';

FLUSH PRIVILEGES;

Przetwarzanie zwrotów (bounces)

phplist powinno posiadać konto typu POP3/IMAP, na które będą "spływać" zwrotki o błędnych adresach (niedostarczonych wiadomości). Dzięki temu jest możliwość automatycznego oznaczania błędnych adresów email odbiorców, aby przy ponownej wysyłce pomijać takie adresy. Konfiguracja takiego konta powinna znaleźć się w pliku konfiguracyjnym (patrz dalej). Więcej można znaleźć w dokumentacji [ 2 ].

Plik konfiguracyjny

Przed przystąpieniem do pierwszego uruchomienia (w przeglądarce) należy ustawić pewne parametry w pliku konfiguracyjnym, tak aby utworzona baza danych oraz wpisane do niej wartości były już poprawne.

// what is your Mysql database server hostname
$database_host = 'localhost';

// what is the name of the database we are using
$database_name = 'phplistdb';

// what user has access to this database
$database_user = 'phplistuser';

// and what is the password to login to control the database
$database_password = '***********';

// Ustawienia dla phpmailer
define('PHPMAILERHOST', 'mx1.bsdserwis.com');
define('PHPMAILERPORT',587);
define("PHPMAILER_SECURE",'tls');
define('PHPMAILER_SMTP_DEBUG', 0);
$phpmailer_smtpuser = 'smtpuser';
$phpmailer_smtppassword = 'smtpauthpassword';

// Zwrotki
$message_envelope = 'biuletyn.zwrotki@uniquework.pl';

// set this to 0, if you set up a cron to download bounces regularly by using the
// commandline option. If this is 0, users cannot run the page from the web
// frontend. Read README.commandline to find out how to set it up on the
// commandline
define('MANUALLY_PROCESS_BOUNCES', 1);

// when the protocol is pop, specify these three
$bounce_mailbox_host = 'pop3.bsdserwis.com';
$bounce_mailbox_user = 'zwrotki@domena.tld';
$bounce_mailbox_password = '***************';
$bounce_mailbox_port = '995/pop3/ssl';

// set this to 0 if you want to keep your messages in the mailbox. this is potentially
// a problem, because bounces will be counted multiple times, so only do this if you are
// testing things.
$bounce_mailbox_purge = 1;

$default_system_language = "pl";
$pageroot = '';
$table_prefix = '';
$usertable_prefix = '';

Ustawienie uprawnień do wybranych katalogów

chown -R www /usr/local/www/phplist/lists/admin/plugins
chown www /usr/local/www/phplist/lists/config
chown www /usr/local/www/phplist/lists/images

# katalog, który trzeba podać w konfiguracji phpList (menu Config)
for d in image files flash; do mkdir -p /var/www/htdocs/virtuals/nowosci-media/public/$d; done
chown -R www /var/www/htdocs/virtuals/nowosci-media/public

Konfiguracja zadań crontab

Zgodnie z dokumentacją [ 3 ] możliwe jest ustawienie zadań CRON przetwarzających kolejki oraz zwroty. Konieczna jest modyfikacja pliku konfiguracyjnego, aby działało to poprawnie:

define('PROCESSCAMPAIGNS_PARALLEL',true);

// define the amount of emails you want to send per period. If 0, batch processing
// is disabled and messages are sent out as fast as possible
define('MAILQUEUE_BATCH_SIZE', 0);

// define the length of one batch processing period, in seconds (3600 is an hour)
define('MAILQUEUE_BATCH_PERIOD', 240);

Kolejnym krokiem jest wykonanie katalogu na logi oraz nadanie uprawnień:

mkdir -p /var/log/phplist
chown www:www /var/log/phplist

Teraz można już wykonać zadanie crontab:

crontab -u www -e

które zawiera następujące linie:

NULL=/dev/null
LOC_PREFIX=/usr/local
SHELL=/bin/sh
PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin
HOME=/var/log
_phplist_cfg=${LOC_PREFIX}/www/phplist/lists/config/config.php

# --- obs/luga phplist -----------------------------------------------------
#
*/5     *       *       *       *       ${LOC_PREFIX}/bin/phplist -c ${_phplist_cfg} -pprocessqueue > /var/log/phplist/process-`/bin/date "+\%H:\%M"`.log
22      01      *       *       *       ${LOC_PREFIX}/bin/phplist -c ${_phplist_cfg} -pprocessbounces > /var/log/phplist/bounces-`/bin/date "+\%w-\%a"`.log 2>&1

Katalog na media do wiadmości newslettera

W celu załączania zdjęć czy innych obiektów multimedialnych w tworzonych wiadomościach, konieczne jest podanie adresu URL do nich. W tym celu został uruchomiony specjalny katalog (mapowany jako https://nowosci.doamain.tld/media/), do którego należy takie materiały umieszczać. Katalog jest dostępny poprzez FTP:

ftp://__user__:__haslo__@nowosci.domain.tld

Pliki, które mają być widoczne z poziomu przeglądarki należy umieścić w katalogu public/.

Można również wykorzystać mechanizm "katalogu zewnętrznego" w ownCloud lub nextCloud

Konfiguracja nginx

Konfiguracja nginx najlepiej wykonać jako root dla danej domeny. Przykładowa konfiguracja:

server {
# [...]
    root /usr/local/www/phplist/lists;
    index index.php;

    location /.well-known/ {}

    location /media/ {
        alias /var/www/htdocs/virtuals/nowosci-media/public/;
        index index.html;
    }
# [...]
}

Użytkowanie interfejsu

Tworzenie list

Pierwszym krokiem jest utworzenie list wysyłkowych i dopisanie do nich użytkowników. Każdy email dopisany do listy musi być potwierdzony (głównie przez użytkownika), tak aby później newsletter trafił do takiego adresu.

Tworzenie wiadomości

Kolejnym krokiem jest utworzenie wiadomości. Nie tylko format oraz treść wiadomości (krok podstawowy), ale również określenie grupy odbiorców (albo całe listy, albo użytkownicy spełniający wybrane kryteria). Na każdym etapie tworzenia wiadomości istnieje możliwość wysłania testowego emaila, tak aby można było zobaczyć, co trafi do odbiorców newslettera. Ostatnim krokiem jest możliwość nałożenia embargo na taką wiadomość do konkretnego czasu w przyszłości¹.

Rozesłanie wiadomości

Po otworzeniu i zapisaniu wiadomości, można je rozesłać² do uczestników list. Są dwa tryby rozsyłania wiadomości: ręczny oraz automatyczny.

Tryb ręczny oznacza, że maile są generowane w momencie wywołania funkcji wysyłki (odnośnik processqueue).
Tryb automatyczny oznacza, że z cron-a jest uruchamiane cyklicznie zadanie, które spowoduje rozsyłanie wiadomości czekających w kolejce. Ten tryb pracy jest zalecany w przypadku posiadania dużej liczby użytkowników. Dodatkowym atutem jest możliwość rozsyłania listów w godzinach wieczornych, czy nocnych kiedy infrastruktura jest zdecydowanie mniej obciążona.

Tips and tricks

Jeżeli panel webowy nie wyświetla się w pełni w języku polskim, to może być konieczne przelogowanie. Oczywiście trzeba się upewnić, że zostały pobrane aktualne tłumaczenia (jedna z pozycji menu konfiguracji).
W wersji 3.4.0 na sztywno jest ustawione sprawdzanie, czy katalog /admin/ nie jest dostępny (poprzez konfigurację nginx) w inny sposób. Być może w kolejnych wersjach będzie możliwa zmiana (czy przysłonięcie) panelu administracyjnego pod inny URL.

Źródła w sieci internet

Odnośniki do dokumentacji

Czyli do danego czasu w przyszłości wiadomość nie zostanie rozesłana. (1)
O ile nie jest nałożone embargo. (2)