Home » Blog
18.May.2014

■ How to setup phpList for background delivery on a linux server

When you want to send a mailout to thousands or hundreds of thousands recipients, you need big gun tools. I was using group mail for long, which is a desktop newsletter tool. Recently I switched to the open source phpList, that runs on the server where the website is hosted. The main advantage is that it can be set to send emails slowly over days if necessary, without having to keep the computer running. Everything is handled remotely on the server.

Only things aren't that simple. phpList is a monster open source project with many versions and revisions and the documentation is, well, open source quality. The recent version 3.0 brought many drastic changes and one can get lost browsing the forums that deal with issues in the older versions. After installing I spent a few days scratching my head trying to figure out cron jobs.

Out of the box phpList is set to work from the internet browser. It runs on the server but it requires an active connection with the desktop browser or it stops working (!). It doesn't make any sense and you can definitely not leave the laptop running for days till the email delivery is complete. The workaround is to process the queue using a cron job, that is using the linux task scheduler on the server. But do you know what on earth is the difference between php-cli and php-cgi? I didn't so I got stuck.

If your website is on shared hosting most probably you only have php-cgi, and that's harder to work with. A good starting point is this forum post that explains how to find out what kind of PHP you have available and what command to use to manually process the phplist queue. Only the information is partial and wrong for the latest version, and it doesn't tell you about the biggest issue: you must schedule the cron job to run repeatedly on the server till all the mails are sent. What you need to do for PHP-cgi is to follow these steps below.

■ PHP-cgi cron setup for phpList v3.x

1. Preparation. Import your email subscribers and start a new campaign. Put the campaign in the processing queue. Follow the steps 1-3 in the forum post. You should revise the mailqueue delivery rate (step 2) to match your cron scheduling (see below)
    
2. Test the command line. Using a SSH connection to the server (e.g. PuTTY) test a single batch of the mailing executing a command like:
   php location/lists/admin/index.php page=pageaction action=processqueue login=user password=xxx > out.htm
   Open the output file out.htm in a browser and search for errors. If everything went well, you should see a message "X messages sent in Y seconds".
   If the output is empty make sure you are running php version 5 or later because that's the minimum requirement. If you have other kind of errors like Access denied search the phpList groups for that keyword to see possible explanations.
    
3. Schedule the delivery. When running in php-cgi mode, you cannot process the list in one go. You have to issue the command again and again till all subscribers are sent their emails. You can read the manual for days but you won't find this important point. Your cron file should look like this
   */5 * * * * /usr/bin/php5 ... (and the rest of the command like in step 2)
   The */5 part means that this should run every 5 minutes to process one batch. Tweak this rate to match your delivery constraints.

You must edit your CONFIG.PHP configuration file so that the delivery rate matches the cron scheduled rate, e.g.

define("MAILQUEUE_BATCH_SIZE",50);
define("MAILQUEUE_BATCH_PERIOD",180); # 180 seconds=3 min
define('MAILQUEUE_THROTTLE',1);

50 emails can be sent in one minute; this runs every 5 minutes so with a simple calculation our rate is (60/5)*50=600 emails/hour.

That's it. Now you can close all the putty and browser windows and go do something useful with your life while the phplist script heralds your news in autopilot mode. If you want to check the progress of the mailing just "login" with your browser to check the active campaign:
http://yoursite.com/lists/admin/?page=messages&tab=active
When it is all over don't forget to remove the cron job using crontab -r command from the putty terminal.

Post a comment on this topic »