phpList 2 E-mail Campaign Manager

By David Young
    Advance your knowledge in tech with a Packt subscription

  • Instant online access to over 7,500+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Installation and Configuration

About this book

Tired of an e-mail BCC list that scrolls off the page, or fiddly and hard-to-manage bulk mailing systems? You need phpList – a high-powered, robust, feature-packed mailing system that will get out of your way and get the job done! You want to know more about phpList?

phpList is a popular open source e-mail campaign manager, sporting a powerful web frontend, rich message editor, and an advanced feature set.

phpList 2 E-mail Campaign Manager will guide you from basic installation and setup through management, reporting, and automation of phpList, the world's most popular open source e-mail campaign manager. It also covers advanced customization and configuration of phpList.

We start with a basic configuration, and finish with a full-featured e-mail management engine. You will work your way up from basic installation to advanced topics such as bounce automation, user and click-through tracking, and integration with third-party tools such as WordPress, Joomla!, Drupal, and Blogger.

Advanced topics such as securing your installation against spammers, attacks, and vulnerabilities are covered, as well as additional advanced and experimental features offered by phpList.

This book is an invaluable guide for any e-mail publisher who wants a robust and powerful engine to manage their small-to-huge e-mail distribution empire.

Publication date:
July 2011


Chapter 1. Installation and Configuration

phpList is a popular open source e-mail campaign manager, sporting a powerful web frontend, rich message editor, and advanced feature set.

Throughout this book, you will be guided from the basics of initial configurations to making advanced customizations and modifications.

The first task required in building our phpList system is the initial installation and configuration of phpList on a web server.

Let's get started!

In this chapter, you will learn how to install and configure a basic phpList system, including:

  • Installing phpList files and database

  • Making configuration changes

  • Basic configuration of lists, users, and attributes

  • Sending your first message


Installing phpList files and database

The phpList system contains HTML and image files, as well as the PHP code, which comprises the phpList. These are static files, and not expected to change, unless you upgrade, or otherwise manually modify them.

The database is where the dynamic content is stored, including lists, members, and messages.

We will install the phpList files and then use a setup process to have phpList set up the database.


For the purposes of this book, we will limit ourselves to the developer-tested system requirements detailed at, namely:

  • A Linux-based platform

  • The Apache web server

  • MySQL database (version 4.0+)

  • PHP (version 4.3+)


    As it will be discussed in detail in Chapter 3, Setting up E-mail Bounce Handling, phpList's bounce handling also requires the php-imap module.

While phpList has been reported to work on Windows servers, by using either IIS or an Apache/PHP/MySQL environment, this book and the examples herein will focus on the Linux-based system described previously.

Downloading phpList

Our first port of call is the phpList download page ( Here we can download the latest version of phpList, packaged either as a ZIP file (typically for Windows users) or TGZ file (typically for Linux users).

Clicking either of the links will auto-start a download of the latest version of phpList in your preferred packaging format:

Unpacking and uploading phpList

Unpack the .ZIP or .TGZ file into a new folder. You'll end up with a directory structure looking something as follows:

Note the three folders named bin, scripts, and public_html. Of these folders, only the public_html folder is required for phpList (like its name, these are the files which will be publicly available on your web server). The other folders are complimentary and contain useful scripts, documentation, and so on.


The structure of the public_html folder assumes that you're going to put phpList at the /lists/ location of your URL—that is, your phpList installation will be accessed at

If you are satisfied with the default /lists/ location, then simply upload the entire lists folder directly to your web server, or else upload the contents of the folder to the preferred location where you want the phpList to be installed on your web server. Remember that this location must be publicly accessible (that is, it must be under the same directory structure as the rest of your publicly accessible web content).

Creating a database

How you create a database for phpList will depend on your web hosting provider, but after the database creation, the following information will be required to configure phpList:

  • Database server hostname (often localhost )

  • Database username

  • Database password

  • Database name

Performing initial configuration

phpList's configuration file is config/config.php. This file is extensive, and contains many advanced settings, which will be dealt with later in this book. For starters, we'll configure some of the basic settings to get our phpList installation running.

Database settings

Starting from line #22, customize the following four entries for the database you created before:

$database_host = "localhost";

Change this to the name of your database host. Leave it as"localhost" if you're not sure—if this doesn't work, contact your hosting provider.

$database_name = "phplistdb";

Change this to the name of the database you created.

$database_user = "phplist";

Change this to the user you created to access the database.

$database_password = "phplist";

Change this to the password of the user you created.

Path settings

If you chose to install phpList to a path other than"/lists" when you uploaded it, you'll also need to change the following two entries, starting at line #48:

$pageroot = '/lists';

Change this to whatever you selected as your phpList path. This could simply be"/" or something else, like"/newsletters"

$adminpages = '/lists/admin';

Change this to match the $pageroot aforementioned definition. phpList requires that the"admin" portion remains the same, so this must be whatever your $pageroot is, with"/admin" added to the end, for example,"/newsletters/admin".

Performing web-based configuration

Access your phpList admin section at the location where you installed it, appending"/admin" to the URL, as follows:


The test mode warning appears because we have not yet disabled test mode in the configuration file, meaning no actual e-mails will be sent. It's helpful to leave phpList in this state until the setup is complete, to avoid accidentally sending e-mails to "live" recipients.

Initialize database

Although it is hard to see because of the pink highlighting, you are warned that the database has not yet been initialized, so click on initialize database to continue:

The database initialization script will automatically connect to the database using the username and password you specified, and will create and populate all the required database tables. If you see any errors, check to see if your database settings are correct. A successful initialization will look like the one in the following screenshot. Having successfully initialized the database, click on the phplist setup link at the bottom of the page to continue:

Initial login

You're now taken to the admin login screen and presented with a user/password request. The default username is admin and the password is phplist. Enter this combination to proceed:

You are then presented with a quick checklist of steps to complete your phpList setup. Start by clicking on go there next to Change Admin Password to change your password:

Change Admin Password

Next, you are taken to the manage admins page (we'll cover this in detail in Chapter 5, List, User, and Administrator Management) and prompted to change the password for the "admin" user.

  1. 1. It's a good idea to associate your e-mail address with this user at the same time. Update the Password and the Email address and click on Save Changes:

  2. 2. You'll notice that when you click on Save Changes, the current page is simply reloaded with a message confirming that the changes have been saved:

  3. 3. To continue with the setup, click on the main page link on the right-hand navigation panel:

  4. 4. We haven't completed the initial checklist yet, so click on the setup link to continue:

  5. 5. The next item on our checklist is Configure General Values, so click on go there to continue:

Configure General Values

You are now taken to the configuration page. This can be accessed in future from the configure link on the right-hand navigation panel. These are the configuration values that are stored in the database, as opposed to the config/config.php file.

There are a few general attributes we should check right away—the rest of them can be tweaked later:

  • Website address (without http://)—This value would have been auto-detected based on the URL which you used to perform the database initialization. Ensure it is correct, because this value is used to create the internal hyperlinks on the web interface.


    If you ever move your phpList installation to another URL, remember to update this value.

  • Person in charge of this system (one e-mail address)—Make sure this address is valid. Notifications of new subscriptions and other system actions will be sent to this address.

You can change a number of other configuration settings, like additional e-mail addresses to receive system notifications, default size of WYSIWYG editor windows, default welcome/confirmation messages, and so on.

Click on the main page link in the right-hand panel to return to the main page. Then click on the setup link to continue the initial setup.

Our next step is the Configure Attributes item, so click on go there to continue:

Configure Attributes

Attributes are used to record additional data about subscribers (such as, name, age, and so on), and to make selective decisions about e-mailing them based on these attributes (that is, you may send a different message to all female subscribers on Mothers' Day).

  1. 1. To get started, click on the predefined defaults link to import some pre-prepared attributes:

  2. 2. Choose the Countries in the world attributes and click on Add:

  3. 3. You can see a simple confirmation message, noting that the attributes have been added. To re-examine these attributes, return to the main admin page by clicking on the main page link:

  4. 4. Note that Country is now displayed under the Configuration functions section. Click on the setup link to continue the setup process:

  5. 5. The next item on our checklist is Create Lists, so click on go there to proceed:

Create Lists

You're now taken to the lists page. This page can also be accessed using the lists link on the right-hand navigation panel.

Currently, there is only a single default list, named test. This list is inactive. We'll use this to test our phpList installation, so click the Active checkbox to make it active, and click on Save Changes to apply:

The lists page will be refreshed with your changes applied. Click on the main page link to return to the main page, and then click once more on the setup link to complete the last item on the checklist.

The final item is labeled Create Subscribe Pages, so click on go there to proceed:

Create Subscribe Pages

You are now taken to the subscribe pages page, which can also be reached using the navigation panel. We will cover subscribe pages in detail in the next chapter, so let's ignore this for now and return to the main page to test message delivery!


Testing e-mail delivery

While we'll cover subscribe pages, bounce handling, and e-mail personalization in subsequent chapters, let's send ourselves a test message to ensure that we're complete with our basic setup.

Create user

As we don't have subscribe pages for automatic user creation (and as we're the administrator anyway), let's add a sample user:

  1. 1.Click on the users link in the navigation panel to go to the users administration page:

  2. 2. Here we see that we currently have zero users. Click on add a user:

  3. 3. To add a new user, complete at least the following fields:

    • Email (the user's e-mail address)

    • Is this user confirmed (set to 1 to create this user as confirmed, opted-in)

    • Mailinglist Membership (check the test list so that we can send e-mails to this user)

  4. 4. You can also complete the following optional fields:

    • Send this user HTML emails (set to 1 to enable HTML for this user)

    • Country (one of the country attributes we imported earlier)

  5. 5. Click on Save Changes to apply.

On saving, the page will refresh, with the user's details permanently on the page, as well as some additional administration links (unsubscribe, history, and so on). Click on back to the list of users to return to the user list:

The user list now shows that we have a single confirmed user, who's subscribed to one list.

Click on the send a message link in the right-hand navigation panel to send your first message:

Sending a message

To send the most basic of messages:

  1. 1. Enter a subject, and some content in the WYSIWYG editor:

  2. 2. Next, click on Save Changes at the very bottom of the page.

  3. 3. The page will be refreshed, with your message saved in a draft state. Now click the Lists tab to choose which lists this message will be sent to:

  4. 4. Choose the test list and then click on Send Message to the Selected Mailinglists to add this message to the queue:

  5. 5. phpList will confirm that the message has been queued and offers you the option to manually process the queue. Click on the process the message queue link to process the queue:

Processing the message queue (in test mode)

Because we haven't yet disabled test mode, no actual e-mail will be sent. phpList will make us aware of this in big, bold, red text. However, this does afford us the opportunity to check that everything else is working as expected:

Disabling test mode

Now that we're confident that we've completed the initial setup correctly, let's disable the test mode, so that we can do a real e-mail delivery.

To disable the test mode, edit config/config.php on line #191 and change this line:

define ("TEST",1);


define ("TEST",0);

Save the file and click on process queue again to send the e-mail for real.

Processing the message queue (for real)

Once you have clicked on process queue again, your message will be processed for real. The test subscriber will receive their message and the list admin will receive a delivery report:


In this chapter, you've learned about how to install and configure phpList, as well as some basic administration tasks, including:

  • Installing phpList files and database

  • Making configuration changes

  • Basic configuration of lists, users, and attributes

  • Sending your first message

In the next chapter, we'll talk about enabling users to subscribe to your lists using subscribe pages and attributes.

About the Author

  • David Young

    David Young's first experience in documenting the open source world was the official 2003 manual for JAJC, a popular jabber client, which he authored in XML using Docbook.

    He followed this with the development of "Bandersnatch", the whimsically named Jabber message logger, which remains the de facto open source platform for recording and archiving messages on a Jabber server.

    After founding and successfully running an open source consulting company ("Funky Penguin") for several years, David "retired" to full-time employment.

    David now works for a respected New Zealand IT consulting firm (Prophecy Networks Ltd) and pursues the odd "Funky Penguin" project in his spare time.

    David's projects, notes, and ramblings can be found at:

    Browse publications by this author
phpList 2 E-mail Campaign Manager
Unlock this book and the full library for $5 a month*
Start now