larger smaller normal text version of this page
Phplist Documentation » Message functions » Process the message queue »

Using a Commandline Script

This page describes how to use a command line script. Keep in mind that commandline processing requires PHP 4.3.0 or higher and PHP-cli. And, obviously, you need to have access to the command line of your server.

Setting up the commandline script

You can use the sample commandline script included in the PHPlist distribution archive. This sample script is called "phplist" and is located in the "bin" directory of the archive. You will have to edit this script to fit your system.

The normal PHPlist access restrictions are bypassed, but the Unix users who are allowed to run the script should be mentioned in the "commandline_users" variable in the config.php file. The identity of a user is determined by the USER environment variable, which may not always match your system.

Sample commandline script: phplist


# script to run PHPlist from commandline. You may need to edit this to make it work
# with your shell environment. The following should work for Bash on Fedora Linux
# but this may vary strongly in other situations. You will need to dig into the
# code to make sure it works for you.

# in commandline mode, access is restricted to users who are listed in the config file
# check README.commandline for more info

# identify the config file for your installation
export CONFIG

# alternatively you can use -c <path to config file> on the commandline

# run the PHPlist index file with all parameters passed to this script
/usr/bin/php /home/website/public_html/lists/admin/index.php $*

Place this script in a directory not accesible to the public (for instance, in /usr/local/scripts/) and make sure it is executable (e.g., chmod 755).

Running PHPlist from the commandline

A few pages in the PHPlist system can (as of version 2.7.0) be run with a simple command from the commandline. Currently you can use "send", "processqueue", "processbounces", and "getrss". The "-p" parameter is the page that needs to be run.

The following examples show how to run PHPlist pages using the commandline script "phplist":

Process the message queue

phplist -pprocessqueue

Process bounces

phplist -pprocessbounces

Send message

The "send" command line requires some more arguments:

-l list the -l parameter can have two types of values, the name of the list or the number of the list. You can add multiple lists or multiple -l parameters.
-s subject the subject can have spaces.
-f from the from is optional. It will default to the system administrator as set up in your config.

You will also need to "pipe" (<) the message into the script.

So, the full "send" command line would look like this:

phplist -psend -s This is the subject -l test 1 2 3 -f < messagefile

Using a cron job to run the command line script

Instead of using shell access every time you need to run the command line script, you can use a cron job to automatically run the script on a scheduled time. Please read Setting up cron jobs for more info.


# (PHP-cli required)
# My config.php file has:
#   $commandline_users = array("user1","user2","user3");
#   define("MAILQUEUE_BATCH_SIZE",200);
#   define("MAILQUEUE_BATCH_PERIOD",3600);
#   define('MAILQUEUE_THROTTLE',5);
#  Every hour at 15 minutes past, we process the queued messages.
#  Every day at 1.10 am, we process bounces.
15 * * * * /usr/local/scripts/phplist -pprocessqueue
10 1 * * * /usr/local/scripts/phplist -pprocessbounces

In this example, the first line of the cron job will execute the command line script "phplist" and process the queue, taking into account the relevant settings in config.php. This will send a message every 5 seconds, batching no more than 200 message per hour. This should be fine for a relatively small list, and if a limit of 220 messages/hour were imposed by an ISP.
The second line will process bounces once a day at 1.10 am.

Page was generated in 0.1335 seconds