[how to] get phplist working with cpanel cron

Solutions for other phpList version 2 users
Forum rules
Please do not ask questions here, this is for Solutions you have discovered or come across.

[how to] get phplist working with cpanel cron

Postby crowdofone » 1:40am, Fri 31 Aug, 2007

:idea: Intro

Back when i first attempted to get phplist working with cPanel it took a ridiculous amount of time and i realized that a couple more hours spent writing some instructions would be nothing if it saved people the hours i'd wasted. Since then i've configured phplist painlessly on quite a few different webhosts and i hope this guide (periodically updated and collected from many, many other posts on the subject) helps make things that little bit easier for you all.

This howto does not cover general installation of phplist, instead it focuses on configuring cpanel to tell phplist to process large numbers of users in scheduled batches.

If you only have a couple of hundred or so email addresses you might want to configure phplist to deliver to all of them in one run when you click on 'Process Queue' rather than go thru the effort of setting up Cron as described here.

:arrow: Stage 1 - Setting $commandline_users in config.php

First we need to set $commandline_users to disabled. Ftp into your webspace and navigate to the phplist directory. Once inside that enter the config directory and download config.php. Now open the file in a text editor and look for a line similar to the one below. Make sure the line is uncommented (no preceding '#') and that it looks exactly like the text shown below:

Code: Select all
$commandline_users = array();

Note the lack of words/characters inside the array() brackets. The above line disables a feature that checks to see whether the 'server user' is authorized to control phplist. Due to us not invoking the $commandline_users feature you shouldn't have to add username and password parameters to the cron line (as discussed later).

If you haven't already you will also need to edit some of the other parameters in config.php such as user details and batch size. Most of these options should be easy enough to work out from the documentation, however one important thing to get right here is the MAILQUEUE_BATCH_SIZE. Your webhost likely imposes a limit on the number of emails you can send (typically per hour). You will need to check with your host to find out what that maximum number is; anywhere between 400 and 1000 emails per hour is common. If you have a subscriber list that's the size of a small town you may want to inquire as to whether they can increase it or as a last resort find an alternative host. Once you know your limit set your batch size to just less than your sending limit. You will also need to set MAILQUEUE_BATCH_PERIOD to whatever the timeframe is. This is set in seconds so a value of 3600 would equal one hour.

Once your all done ftp the file back up to your web space in place of the original.

:arrow: Stage 2 - Configuring cron

Next we will need to tell Cron to process the queue every hour. In your cpanel select the Cron icon and choose the 'Standard' experience level option. In the 'Command to run:' textbox stick the following text (it's all one line) but change *CPANELUSERNAME* and *PHPLISTDIR* to your own):

Code: Select all
/usr/local/bin/php /home/*CPANELUSERNAME*/public_html/*PHPLISTDIR*/admin/index.php -p processqueue

Note: In some scenarios *CPANELUSERNAME* may be your domain name (ie: '/home/joebloggs.com/...' rather than '/home/joebloggs/...')

You will also need to select the regularity you want Cron to run at. Typically if your MAILQUEUE_BATCH_PERIOD value is set to 3600 (1 hour) then you will want to set Cron to run every hour, of each day & month.

For testing I recommend setting it to a frequency of 'every other minute' of every hour, day & month to test with. This means it will be attempting to send emails (ie: process the queue) every two minutes.

Now in the phplist admin click on 'Send a message' and create a basic mailout. Save it, select the 'List' tab in messages, select the 'test' list (make sure your email address is signed up to it) and click on 'Send to selected mailinglists'. Do NOT press 'Process queue' afterwards. It's Cron's job to automatically start the process queue routine for you based on the instructions you entered above. The 'test' list was present by default with my phplist installation however if no such list is present you will want to create one yourself.

Assuming you set it up correctly Cron should send you an error/confirmation email each time it is set to run (receiving any Cron emails, even errors, is good news as it means the Cron part is working).

Once you have phplist successfully sending mailouts you will want add: " > /dev/null" to the end of the line to stop it from sending all those confirmation mails and flooding your inbox. The final output looks like this:

Code: Select all
/usr/local/bin/php /home/*CPANELUSERNAME*/public_html/*PHPLISTDIR*/admin/index.php -p processqueue > /dev/null

You will also want to revert Cron from sending messages every 2 minutes and set it to the equivalent of MAILQUEUE_BATCH_PERIOD as described above.

Hopefully you should now have everything working however if your still not up and running read on....

:!: Troubleshooting

If you are receiving emails with error messages from cron try entering the text (or part thereof) in the forum search to get a better idea of the problem and (usually) find a fix to the issue.

If you are receiving some sort of email from Cron, but it is not sending the newsletter to anyone try tweaking the Cron command text. Have a look at some other forum posts on this issue and try any alternative command strings people are using. Some people might find that lengthening their string to add the path to config.php helps:

Code: Select all
/usr/local/bin/php /home/*CPANELUSERNAME*/public_html/*PHPLISTDIR*/admin/index.php -pprocessqueue -c/home/*CPANELUSERNAME*/public_html/*PHPLISTDIR*/config/config.php

Another is to change the path to php from:

Code: Select all
/usr/local/bin/php [...]


Code: Select all
/usr/bin/php [...]

or, whatever directory your webhost has it setup as (use phpinfo() to find out).


If you only seem to be sending a limited number of emails, or your account is being locked out, or it works sometimes and other times not then remember that your webhost is probably imposing a limit on the number of emails you can send and this may be affecting phplist's sending abilities.

For some hosts it seems that you may need to use $commandline_users = array(USERNAME) rather than $commandline_users = array();

You will also need to change the cron line adding login=USERNAME password=PASSWORD as below

Code: Select all
/usr/local/bin/php /home/*CPANELUSERNAME*/public_html/*PHPLISTDIR*/admin/index.php -pprocessqueue login=USERNAME password=PASSWORD -c/home/*CPANELUSERNAME*/public_html/*PHPLISTDIR*/config/config.php

In the above situatiuons USERNAME (not CPANELUSERNAME) is specifed in phplist's README.commandline as the UNIX user. This would suggest that USERNAME should, in my interpretation, be the same as your cPanel user (the *CPANELUSERAME*). A later post in this thread however suggests they had success using the USERNAME (and assocaited PASSWORD) of the phplist admin.


This is a confusing matter that i have not gotten to the bottom of in over 3 years as most every installation i have done works fine without setting $commandline_users = array(USERNAME). If anyone can shed some light on what parameters should be given, and under what circumstances they are needed then please chip in.

Lastly it's also worth mentioning that your host will need to have the command line version of php enabled (php comes in two versions: command line and cgi). While the large majority of webhosts do supply a command line version if you encounter problems you should always contact them to check.

If your host does not have the command line version of php installed there are other ways of triggering the Process Queue through Cron. A great howto on how to do this can be found here...


Thanks for reading and if you have any additions or corrections post them below and I'll update this first post. Cheers.

Ps. More info here....


Last edited by crowdofone on 12:41pm, Mon 07 Jun, 2010, edited 19 times in total.
PL Nut
Posts: 16
Joined: 9:20pm, Thu 30 Aug, 2007

Many thanks!

Postby geoffb63 » 5:56pm, Fri 07 Sep, 2007

Your setup for cpanel cronjobs is a lifesaver!

I have tried all the suggested setups with no luck.

This is the first mention I have seen of editing the config.php file and it made all the difference.

Thank you so much, I can finally use the program.
phpList newbie
Posts: 1
Joined: 5:48pm, Fri 07 Sep, 2007

Postby crowdofone » 12:15am, Sat 08 Sep, 2007

No problem, was just so happy to have finally got it working i figured i should probably write a little guide for anyone else that's struggling. Great to hear its working for you and thanks for signing up just to say thanks!
PL Nut
Posts: 16
Joined: 9:20pm, Thu 30 Aug, 2007

Postby darren1 » 1:39pm, Thu 20 Sep, 2007

Hi guys............ ive tried for the last week to get this up and running to send a mail out automatically once a week........ still no luck :( desperate now to get it up and running, i dont think i can be that far away! just for the record i have searched the forums etc, tried different advice and im posting here as a last resort....

Heres what ive done so far......

Turned on the repetition option in config file.

Set up a test list with 1 email (my email) to send the message.

Created a new message as normal, go to the schedule screen and set the embargo until time i want to send the first message, repeat hourly (just to test it working), then set the embargo until as 2 days later.

I then go to lists select my test list and hit send to selected mailing lists. I DONT PROCESS THE QUEUE. I understand that this is the part where the cron should kick in, and me pressing process queue is what i would do manually to send the message. i want to send it automatically without any intervention from me.

ive then gone to my cPanel STANDARD cron jobs entered the following info:

public_html/MY DIRECTORY/admin/index.php -p processqueue -c/home/MY SERVER/public_html/MY DIRECTORY/config/config.php

Then set it to every 15 mins, every hour, every day, every weekday, every month.

also for the record, ive edited my config file so this is showing:

$commandline_users = array();

and coded out with a # the following:

#$commandline_users = array("MY SERVER");


Ive been using php fine manually for the last 12 months and dont have any problems sending messages. All im hoping to achieve by doing this is to send the same message, every week, to all people on my list, without me needing to do it manually. I want to send the message repeatedly (each week) even if the user has received it the week before.

All in all nothing seemed to be happening.... no message sent, no cron report recieved or send report from phplist.

I hope this all makes sense and someone can point me in the right direction as ive hit a brick wall now and any help is appreciated :(

Thank you in advance!
phpList newbie
Posts: 3
Joined: 10:17am, Sun 23 Apr, 2006

Postby crowdofone » 10:44pm, Mon 24 Sep, 2007

Looks like the cron part isn't working :x

First I'd double check the email address that Cron messages are meant to be appearing at ... Right at the top of the 'Standard' Cron page there's a text box and the words 'Please enter an email address where the cron output will be sent:'. Check that!

Else just try playing around with Cron. Another command I tried using (unsuccessfully) but that did at at least send me messages was:

curl -s http://MYDOMAIN/phplist/admin/?page=processqueue

Also .. considering you've got come this far it's probably worth hitting up your ISP to ask if Cron jobs are supported and to have them check n see whether their actually being processed.

[Edits due to previous link spam checking (even though i've been registered way over 10 days). Seems to be working today so have removed original obfuscation ... Was funny that it wouldn't even accept the word ' curl ' before tho!]

Last edited by crowdofone on 12:49pm, Tue 25 Sep, 2007, edited 4 times in total.
PL Nut
Posts: 16
Joined: 9:20pm, Thu 30 Aug, 2007

Postby flyerfixer » 4:55am, Tue 25 Sep, 2007

thanks for the help I will need to use that very soon!
Posts: 13
Joined: 12:05pm, Thu 06 Sep, 2007

Postby missp » 4:42am, Sat 29 Mar, 2008

I was/am so thrilled to find this ... but so far, no joy. I am getting the cron report email, but no actual test email arriving to my 2 subscribed addresses.

I am concerned that all of my previous attempts left me with something awry in the rest of the config file. Such as ...

Do we want batch processing on/off? etc?
PL Nut
Posts: 33
Joined: 2:48am, Mon 10 May, 2004

Postby crowdofone » 7:23pm, Sun 30 Mar, 2008

I'm not familiar with batch processing 'on/off' being an option in config.php.

AFAIK you can just set the length of a batch session and the maximum number of emails sent during that session.

I would imagine that batch processing is simply a result of having a working cron implementation.

If you can start the mailout manually (by clicking on process queue) and the messages are arriving then it's unlikely to be an issue with the server sending out mail, as all the cron command is doing is pressing the 'process queue' button for you.

I sometimes find that if I send a message and then
edit & requeue it in order to send to a different list then it won't actually send anything even though it says in the eventlog that those messages were sent successfully.

Therefore for each test I'd recommend you always create new messages and try sending them rather than requeuing an old test newsletter that didn't arrive.

Also try:

Sending to email addresses with a different domain from the one(s) your currently using.

Checking that your 'from:' address actually exists (never known this to be a problem ...)

Checking that the two emails addresses you are using are properly separated in the admin.

Posting an email with your cron output here so we can see what messages you are receiving.
PL Nut
Posts: 16
Joined: 9:20pm, Thu 30 Aug, 2007

Postby missp » 11:47pm, Sun 30 Mar, 2008

Well for starters, here's the email I get from Cron:

Usage: php [options] [-f] <file> [args...]
php [options] -r <code> [args...]
php [options] [-- args...]
-a Run interactively
-c <path>|<file> Look for php.ini file in this directory
-n No php.ini file will be used
-d foo[=bar] Define INI entry foo with value 'bar'
-e Generate extended information for debugger/profiler
-f <file> Parse <file>.
-h This help
-i PHP information
-l Syntax check only (lint)
-m Show compiled in modules
-r <code> Run PHP <code> without using script tags <?..?>
-s Display colour syntax highlighted source.
-v Version number
-w Display source with stripped comments and whitespace.
-z <file> Load Zend extension <file>.

args... Arguments passed to script. Use -- args when first argument
starts with - or script is read from stdin
PL Nut
Posts: 33
Joined: 2:48am, Mon 10 May, 2004

Postby crowdofone » 12:51am, Mon 31 Mar, 2008

That's the standard commandline output for php, so at a guess i'd say your path's wrong. Check that you've replaced *USERNAME* and *PHPLISTDIR* with your own details and that if your running phplist from a sub-sub-directory of your account that you've included that too.

/usr/local/bin/php -q/home/*USERNAME*/public_html/*PHPLISTDIR*/admin/index.php -p processqueue -c/home/*USERNAME*/public_html/*PHPLISTDIR*/config/config.php

Let us know how it goes.
PL Nut
Posts: 16
Joined: 9:20pm, Thu 30 Aug, 2007

Postby missp » 1:42am, Mon 31 Mar, 2008

That's what I thought -- just generic cron info. But my path is correct:

My phplist is installed in the directory: /public_html/lists/

So the cron looks like this:

/usr/local/bin/php -q/home/mysiteusername/public_html/lists/admin/index.php -p processqueue -c/home/mysiteusername/public_html/lists/config/config.php

And is set for every 5 minutes * every hour * every day * every month

I created a new message, clicked to send to the selected list which is my Test list. 3 addresses, one gmail, two are on the same VPS but different domain names from the one I am trying to send from.

My "From" address does exist.

Yes, mail goes out when I do it manually (although I am usually forced to push it again several times throughout the process as my browser times out and it can take 3 days to get 6,000 messages sent (at 500/hour) which is ridiculous! It's as if they will process themselves up to a point, but then stop).

So I'm rather desperate to get cron working so I can just rest easy knowing my full list will receive a message without my spending the weekend checking up on it.

So with the above info, I just tried again and got the same cron email sent to my "send From" admin address. The "subject line" displays the actual cron command. And no emails have been delivered.

Thinking the issue might be with the usr/local/bin/php path, I just tried usr/bin/php

which had the same results (or should I say, non-results).

Then I looked at the PHP Configuration from this domain's cpanel and it shows for paths and directories:

So trying again with usr/local/lib/php

and this time the cron output returned:
/bin/sh: /usr/local/lib/php: is a directory

Just stumped here. I guess the path problem is the pointer to php though so maybe I need to go to my host for that end of the info. Yes?
PL Nut
Posts: 33
Joined: 2:48am, Mon 10 May, 2004

Postby Ernesto » 2:40am, Mon 31 Mar, 2008

missp wrote:That's what I thought -- just generic cron info. But my path is correct:

My phplist is installed in the directory: /public_html/lists/

So the cron looks like this:

/usr/local/bin/php -q/home/mysiteusername/public_html/lists/admin/index.php -p processqueue -c/home/mysiteusername/public_html/lists/config/config.php

It seems to me you are in fact succesfully invoking PHP, considering that you get PHP's commandline options. So, the path to PHP should be correct. Something must be wrong with your arguments. Try leaving out the "-q", and remove the space after "-p"
Search first, Ask questions later...
PL Freak!
Posts: 592
Joined: 2:25am, Thu 08 Jun, 2006

Postby missp » 3:14am, Mon 31 Mar, 2008

Ernesto you are a genius!!! IT WORKED!!!!!!

Thank you soo much :D :D :D

Here is the cron entry that worked:

Code: Select all
/usr/local/bin/php /home/mysiteusername/public_html/lists/admin/index.php -pprocessqueue -c/home/mysiteusername/public_html/lists/config/config.php
PL Nut
Posts: 33
Joined: 2:48am, Mon 10 May, 2004

Postby Ernesto » 4:52pm, Mon 31 Mar, 2008

Glad to have been of help, though major credit should be given to Crowdofone for posting and supporting this [how to] thread!

Cheers! 8)
Search first, Ask questions later...
PL Freak!
Posts: 592
Joined: 2:25am, Thu 08 Jun, 2006

Postby missp » 4:57pm, Mon 31 Mar, 2008

Oh absolutely! Crowdofone has finally resolved what was feeling like an impossible issue! I am immensely grateful for this thread and all the support. THANK YOU
PL Nut
Posts: 33
Joined: 2:48am, Mon 10 May, 2004


Return to Answers, Howtos, Tips & Tricks

Who is online

Users browsing this forum: No registered users and 2 guests