larger smaller normal text version of this page
Translations: es fr nl

phplist Documentation Installation

Configuring your phpList Installation

This page contains information on how to configure the configuration file (config.php) of your phpList installation. Later on, some additional settings will need to be configured in the configuration page of the Admin backend module.

The following settings in the config.php file must be configured for phplist to work on your server. The settings will enable phplist to connect to your database, to send emails and receive bounced emails, as well as a number of important security and optional features (HTML, RSS, Attachments, sending criteria, etc.)

This file is usually found in usr/public_html/lists/config/config.php
  1. Settings for database connection & web pages
  2. Settings for handling bounces
  3. Setting the Send Speed (Rate)
  4. Choosing the language
  5. Security related settings
  6. Debugging and informational
  7. Feedback to developers
  8. Miscellaneous
  9. Experimental Features
  10. Advanced Features, HTML editor, RSS, Attachments, Plugins. PDF creation

Important note: the settings indicated below are default settings. Many of these settings have to be configured to work with your system. If you are unable to configure section 1 properly you should contact someone who is more knowledgeable about how your system works.

Choosing the language

The phpList public interface (frontend) has been translated into many languages (localization files reside in /lists/texts). Choose the one you want here.

# select the language module to use
# Look for <country>.inc files in the texts directory
# to find your language
# this is the language for the frontend pages. In the admin pages you can
# choose your language by using the dropdown in the pages (since ver.2.10.3).
$language_module = "";

Note: Other language files than may need to be updated. The availability of translations does not always keep pace with new releases of phplist, and new text strings added in may still have to be added and translated in other languague files.

Require login

# set this to 1 if you want PHPlist to deal with login for the administrative
# section of the system
# you will be able to add administrators who control their own lists
# default login is "admin" with password "phplist"
$require_login = 1;

Maximum number of lists

# if you use login, how many lists can be created per administrator

Command line users

# if you use commandline, you will need to identify the users who are allowed to run
# the script. See README.commandline for more info
$commandline_users = array("admin");
# or you can use the following to disable the check (take off the # in front of the line)
# $commandline_users = array();

Ask for user password

# as of version 2.4.1, you can have your users define a password for themselves as well
# this will cause some public pages to ask for an email and a password when the password is
# set for the user. If you want to activate this functionality, set the following
# to 1. See README.passwords for more information

Unsubscribe requires password

# if you also want to force people who unsubscribe to provide a password before
# processing their unsubscription, set this to 1. You need to have the above one set
# to 1 for this to have an effect

Unsubscribe jump-off

# if a user should immediately be unsubscribed, when using their personal URL, instead of
# the default way, which will ask them for a reason, set this to 1

Blacklist grace time

# when a user unsubscribes they are sent one final email informing them of
# their unsubscription. In order for that email to actually go out, a gracetime
# needs to be set otherwise it will never go out. The default of 5 minutes should
# be fine, but you can increase it if you experience problems
$blacklist_gracetime = 5;

Check for session IP

# to increase security the session of a user is checked for the IP address
# this needs to be the same for every request. This may not work with
# network situations where you connect via multiple proxies, so you can
# switch off the checking by setting this to 0

Encrypt user passwords

# if you use passwords, you can store them encrypted or in plain text
# if you want to encrypt them, set this one to 1
# if you use encrypted passwords, users can only request you as an administrator to
# reset the password. They will not be able to request the password from
# the system

Check for host

# Check for host of email entered for subscription
# Do not use it if your server is not 24hr online
# make the 0 a 1, if you want to use it
$check_for_host = 0;

Debugging and informational

Test mode

# if test is true (not 0) it will not actually send ANY messages,
# but display what it would have sent
define ("TEST",1);


# if you set verbose to 1, it will show the messages that will be sent. Do not do this
# if you have a lot of users, because it is likely to crash your browser
# (it does mine, Mozilla 0.9.2, well 1.6 now, but I would still keep it off :-)
define ("VERBOSE",0);

Warn about PHP settings

# some warnings may show up about your PHP settings. If you want to get rid of them
# set this value to 0

Manually process queue

# If you set up your system to send the message automatically, you can set this value
# to 0, so "Process Queue" will disappear from the site
# this will also stop users from loading the page on the web frontend, so you will
# have to make sure that you run the queue from the commandline
# check README.commandline how to do this

Send mail queue processing report

# after every run of the queue to send out messages, phpList will send a summary to the
# admin address. If you want to stop this, set this to false or 0

Workaround Outlook bug

# if you want to use \r\n for formatting messages set the 0 to 1
# see also
# this is likely to break things for other mailreaders, so you should
# only use it if all your users have Outlook (not Express)

User history system info

# user history system info.
# when logging the history of a user, you can specify which system variables you
# want to log. These are the ones that are found in the $_SERVER and the $_ENV
# variables of PHP. check
# the values are different per system, but these ones are quite common.
$userhistory_systeminfo = array(

Feedback to developers


# use Register to "register" to Once you set TEST to 0, the system will then
# request the "Powered By" image from, instead of locally. This will give me
# a little bit of an indication of how much it is used, which will encourage me to continue
# developing PHPlist. If you do not like this, set Register to 0.
define ("REGISTER",1);


# We request you retain some form of credits on the public elements of
# PHPlist. These are the subscribe pages and the emails.
# This not only gives respect to the large amount of time given freely
# by the developers but also helps build interest, traffic and use of
# PHPlist, which is beneficial to future developments.
# By default the webpages and the HTML emails will include an image and
# the text emails will include a powered by line

# If you want to remove the image from the HTML emails, set this constant
# to be 1, the HTML emails will then only add a line of text as signature

# if you want to also remove the image from your public webpages
# set the next one to 1, and the pages will only include a line of text

# in order to get some feedback about performance, PHPlist can send statistics to a central
# email address. To de-activate this set the following value to 1

# this is the email it will be sent to. You can leave the default, or you can set it to send
# to your self. If you use the default you will give me some feedback about performance
# which is useful for me for future developments
# $stats_collection_address = '';


Number of criterias

# the number of criterias you want to be able to select when sending a message.
# Useful is is to make it the same as the number of selectable attributes you enter in the
# system, but that is up to you (selectable = select, radio or checkbox)
define ("NUMCRITERIAS",2);

Allow non-list subscribe

# if you do not require users to actually sign up to lists, but only want to
# use the subscribe page as a kind of registration system, you can set this to 1 and
# users will not receive an error when they do not check a list to subscribe to

Mail queue batch processing

# batch processing
# batch processing
# if you are on a shared host, it will probably be appreciated if you don't send
# out loads of emails in one go. To do this, you can configure batch processing.
# Please note, the following two values can be overridden by your ISP by using
# a server wide configuration. So if you notice these values to be different
# in reality, that may be the case

## if you send the queue using your browser, you may want to consider settings like this
## which will send 10 messages and then reload the browser to send the next 10. However, this
## will not restrict the sending to any limits, so there's a good chance you will
## go over the limits of your ISP
# define("MAILQUEUE_BATCH_SIZE",10);

## if you send the queue using commandline, you can set it to something that complies with the
## limits of your ISP, eg 300 messages an hour would be
# define("MAILQUEUE_BATCH_SIZE",300);
# define("MAILQUEUE_BATCH_PERIOD",3600);
# and then you need to set the cron to run every 5 minutes

# 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 the length of one batch processing period, in seconds (3600 is an hour)
# Please note: this setting has two consequences:
# 1. it will enforce that the amount of emails sent in the period identified here does not exceed the amount
# 2. there will be a delay of MAILQUEUE_BATCH_PERIOD when running the queue.
# number 1 is mostly when using commandline queue processing (strongly recommended)
# number 2 is when using browser queue processing. The browser will reload to send the next
# batch after the amount of seconds set here


Mail queue throttle

# to avoid overloading the server that sends your email, you can add a little delay
# between messages that will spread the load of sending
# you will need to find a good value for your own server
# value is in seconds (or you can play with the autothrottle below)

Year ranges for date attributes

# year ranges. If you use dates, by default the drop down for year will be from
# three years before until 10 years after this the current value for year. If there
# is no current value the current year will be used.
# if you want to use a bigger range you can set the start and end year here
# be aware that the drop down may become very large.
# if set to 0 they will use the default behaviour. So I'm afraid you can't start with
# year 0. Also be aware not to set the end year to something relatively soon in the
# future, or it will stop working when you reach that year.

Empty value prefix

# empty value prefix. This can be used to identify values in select attributes
# that are not allowed to be selected and cause an error "Please enter your ..."
# by using a top value that starts with this string, you can make sure that the
# selects do not have a default value, that may be accidentally selected
# eg. "-- choose your country"

Admin details for messsages

# admin details for messages
# since ver. 2.10.3 if this is enabled phplist will initialise the From in new messages to be the
# details of the logged in administrator who is sending the message
# otherwise it will default to the values set in the configure page that identify
# the From for system messages

Test messages

# test emails
# if you send a test email, phplist will by default send you two emails, one in HTML format
# and the other in Text format. Since ver. 2.10.3, if you set this to 1, you can override this behaviour
# and only have a test email sent to you that matches the user record of the user that the
# test emails are sent to

Experimental Features

List exclude

# list exclude will add the option to send a message to users who are on a list
# except when they are on another list.
# this is currently marked experimental


Admin authentication module

# admin authentication module.
# to validate the login for an administrator, you can define your own authentication module
# this is not finished yet, so don't use it unless you're happy to play around with it
# if you have modules to contribute, open a tracker issue on
# the default module is, which you can find in the "auth" subdirectory of the
# admin directory. It will tell you the functions that need to be defined for phplist to
# retrieve it's information.
# phplist will look for a file in that directory, or you can enter the full path to the file

# eg
#$admin_auth_module = '';

# or
#$admin_auth_module = '/usr/local/etc/';

Stacked attribute selection

# stacked attribute selection
# this is a new method of making a selection of attributes to send your messages to
# to start with, it doesn't seem to work very well in Internet Explorer, but it works fine
# using Mozilla, Firefox, Opera (haven't tried any other browsers)
# so if you use IE, you may not want to try this.

# stacked attribute selection allows you to continuously add a selection of attributes
# to your message. This is quite a bit more powerful than the old method, but it can also
# cause very complex queries to be constructed that may take too long to calculate
# If you want to try this, set the value to 1, and give us feedback on how it's going

# if you want to use dates for attribute selections, you need to use this one

Send a webpage

# send a webpage. You can send the contents of a webpage, by adding
# [URL:http://website/file.html] as the content of a message. This can also be personalised
# for users by using eg
# [URL:http://website/file.html?email=[email]]
# the timeout for refetching a URL can be defined here. When the last time a URL has been
# fetched exceeds this time, the URL will be refetched. This is in seconds, 3600 is an hour
# this only affects sending within the same "process queue". If a new process queue is started
# the URL will be fetched the first time anyway. Therefore this is only useful is processing
# your queue takes longer than the time identified here.

Mailqueue auto-throttle

# Mailqueue autothrottle. This will try to automatically change the delay
# between messages to make sure that the MAILQUEUE_BATCH_SIZE (above) is spread evently over
# MAILQUEUE_BATCH_PERIOD, instead of firing the Batch in the first few minutes of the period
# and then waiting for the next period. This only works with mailqueue_throttle off
# it still needs tweaking, so send your feedback to if you find
# any issues with it

Click tracking

# Click tracking
# If you set this to 1, all links in your emails will be converted to links that
# go via phplist. This will make sure that clicks are tracked. This is experimental and
# all your findings when using this feature should be reported to mantis
# for now it's off by default until we think it works correctly

# Click track, list detail
# if you enable this, you will get some extra statistics about unique users who have clicked the
# links in your messages, and the breakdown between clicks from text or html messages.
# However, this will slow down the process to view the statistics, so it is
# recommended to leave it off, but if you're very curious, you can enable it

Domain throttling

# Domain Throttling
# You can activate domain throttling, by setting USE_DOMAIN_THROTTLE to 1
# define the maximum amount of emails you want to allow sending to any domain and the number
# of seconds for that amount. This will make sure you don't send too many emails to one domain
# which may cause blacklisting. Particularly the big ones are tricky about this.
# it may cause a dramatic increase in the amount of time to send a message, depending on how
# many users you have that have the same domain (eg
# if too many failures for throttling occur, the send process will automatically add an extra
# delay to try to improve that. The example sends 1 message every 2 minutes.

Domain auto-throttle

# if you have very large numbers of users on the same domains, this may result in the need
# to run processqueue many times, when you use domain throttling. You can also tell phplist
# to simply delay a bit between messages to increase the number of messages sent per queue run
# if you want to use that set this to 1, otherwise simply run the queue many times. A cron
# process every 10 or 15 minutes is recommended.

Admin language

# admin language
# if you want to disable the language switch for the admin interface (and run all in english)
# set this one to 0

Advanced bounce processing

# advanced bounce processing
# with advanced bounce handling you are able to define regular expressions that match bounces and the
# action that needs to be taken when an expression matches. This will improve getting rid of bad emails in
# your system, which will be a good thing for making sure you are not being blacklisted by other
# mail systems
# if you use this, you will need to teach your system regularly about patterns in new bounces

Spam block

Since version 2.10.4 you can use the experimental spam block setting to detect spam bots.

# add spamblock
# if you set this to 1, phplist will try to check if the subscribe attempt is a spambot trying to send
# nonsense. If you think this doesn't work, set this to 0
# this is currently only implemented on the subscribe pages

# notify spam
# when phplist detects a possible spam attack, it can send you a notification about it
# you can check for a while to see if the spam check was correct and if so, set this value
# to 0, if you think the check does it's job correctly.
# it will only send you emails if you have "Does the admin get copies of subscribe, update and unsubscribe messages"
# in the configuration set to true


# CHECK REFERRER. Set this to "true" to activate a check on each request to make sure that
# the "referrer" in the request is from ourselves. This is not failsafe, as the referrer may
# not exist, or can be spoofed, but it will help a little
# it is also possible that it doesn't work with Webservers that are not Apache, we haven't tested that.

# if you activate the check above, you can add domain names in this array for those domains
# that you trust and that can be allowed as well
# only mention the domain for each.
# for example: $allowed_referrers = array('','','','');
$allowed_referrers = array();

Advanced Features, HTML editor, RSS, Attachments, Plugins, PDF creation

Message encoding

# you can specify the encoding for HTML and plaintext messages here. This only
# works if you do not use the phpmailer (see below)
# the default should be fine. Valid options are 7bit, quoted-printable and base64


# PHPlist can send RSS feeds to users. Feeds can be sent daily, weekly or
# monthly. To use the feature you need XML support in your PHP installation, and you
# need to set this constant to 1

# if you have set up a cron to download the RSS entries, you can set this to be 0


# the FCKeditor is now included in PHPlist, but the use of it is experimental
# if it's not working for you, set this to 0
# NOTE: If you enable TinyMCE please disable FCKeditor and vice-versa.

# If you want to upload images to the FCKeditor, you need to specify the location
# of the directory where the images go. This needs to be writable by the webserver,
# and it needs to be in your public document (website) area
# the directory is relative to the root of PHPlist as set above
# This is a potential security risk, so read for more information

TinyMCE editor

# TinyMCE Support (
# It is suggested to copy the tinymce/jscripts/tiny_mce directory from the
# standard TinyMCE distribution into the public_html/lists/admin/plugins
# directory in order to keep the install clean.
# NOTE: If you enable TinyMCE please disable FCKeditor and vice-versa.
# Set this to 1 to turn on TinyMCE for writing messages:
define("USETINYMCEMESG", 0);
# Set this to 1 to turn on TinyMCE for editing templates:
# Set this to path of the TinyMCE script, relative to the admin directory:
define("TINYMCEPATH", "plugins/tiny_mce/tiny_mce.js");
# Set this to the language you wish to use for TinyMCE:
define("TINYMCELANG", "en");
# Set this to the theme you wish to use.  Default options are: simple, default and advanced.
define("TINYMCETHEME", "advanced");
# Set this to any additional options you wish.  Please be careful with this as you can
# inadvertantly break TinyMCE.  Rever to the TinyMCE documentation for full details.
# Should be in the format: ',option1:"value",option2:"value"'   <--- note comma at beginning
define("TINYMCEOPTS", "");

Manual text part

# Manual text part, will give you an input box for the text version of the message
# instead of trying to create it by parsing the HTML version into plain text


# attachments is a new feature and is currently still experimental
# set this to 1 if you want to try it
# caution, message may become very large. it is generally more
# acceptable to send a URL for download to users
# if you try it, it will be appreciated to give feedback to the
# users mailinglist, so we can learn whether it is working ok
# using attachments requires PHP 4.1.0 and up

# if you use the above, how many would you want to add per message (max)
# You can leave this 1, even if you want to attach more files, because
# you will be able to add them sequentially

# when using attachments you can upload them to the server
# if you want to use attachments from the local filesystem (server) set this to 1
# filesystem attachments are attached at real send time of the message, not at
# the time of creating the message

# if you add filesystem attachments, you will need to tell PHPlist where your
# mime.types file is.

# if a mimetype cannot be determined for a file, specify the default mimetype here:

Attachment repository

# the attachment repository is the place where the files are stored (if you use
# this needs to be writable to your webserver user
# it also needs to be a full path, not a relative one
# for secutiry reasons it is best if this directory is not public (ie below
# your website document root)
$attachment_repository = '/tmp';


# you can create your own pages to slot into PHPlist and do certain things
# that are more specific to your situation (plugins)
# if you do this, you can specify the directory where your plugins are. It is
# useful to keep this outside the PHPlist system, so they are retained after
# upgrading
# there are some example plugins in the "plugins" directory inside the
# admin directory
# this directory needs to be absolute, or relative to the admin directory


# uncomment this one to see the examples in the system (and then comment the
# one above)


# if you want to be able to send your messages as PDF attachments, you need to install
# FPDF ( and set these variables accordingly

# define('FPDF_FONTPATH','/home/pdf/font/');
# require('fpdf.php');
# define("USE_PDF",1);
# $pdf_font = 'Times';
# $pdf_fontstyle = '';
# $pdf_fontsize = 14;


# the mime type for the export files. You can try changing this to
# application/ to make it open automatically in excel
$export_mimetype = 'application/csv';

# if you want to use export format optimized for Excel, set this one to 1


# Repetition. This adds the option to repeat the same message in the future.
# After the message has been sent, this option will cause the system to automatically
# create a new message with the same content. Be careful with it, because you may
# send the same message to your users
# the embargo of the message will be increased with the repetition interval you choose
# also read the README.repetition for more info


# Prepare a message. This system allows you to create messages as a super admin
# that can then be reviewed and selected by sub admins to send to their own lists
# it is old functionality that is quite confusing, and therefore by default it
# is now off. If you used to use it, you can switch it on here. If you did not
# use it, or are a new user, it is better to leave it off. It has nothing to
# do with being able to edit messages.

Forward to a friend - retain attributes

#0011857: forward to friend, retain attributes
# When forwarding ('to a friend') the message will be using the attributes of the destination email by default.
# This often means the message gets stripped of al its attributes.
# When setting this constant to 1, the message will use the attributes of the forwarding user. It can be used
# to connect the destinatory to the forwarder and/or reward the forwarder.

Forward to a friend - multiple emails

#0011860: forward to friend, multiple emails
# This setting defines howmany email addresses you can enter in the forward page.
# Default is 1 to not change behaviour from previous version.

Forward to a friend - personal message

#0011996: forward to friend - personal message  (since ver. 2.10.7)
# Allow user to add a personal note when forwarding 'to a friend'
# 0 will turn this option off. default is 0 to not change behaviour from previous version.
# 500 is recommended as a sound value to write a little introductory note to a friend
#The note is prepeded to both text and html messages and will be stripped of all html

Forward to a friend - different content

#0013076: different content when forwarding 'to a friend'  (since ver. 2.10.7)
# Allow admin to enter a different message that will be sent when forwarding 'to a friend'
# This will show an extra tab in the message dialog.

Forward to a friend - Lead Ref Scheme

#0013845 Lead Ref Scheme  (since ver. 2.10.7)
# When this setting has a value <> '' all succesfull handovers to the MTA will be counted
# and saved in the attribute with the name of this setting.

Mail server

# If you want to use the PHPMailer class from, set the following
# to 1. If you tend to send out html emails, it is recommended to do so.

# To use a SMTP please give your server hostname here, leave it blank to use the standard
# PHP mail() command.

# if you want to use smtp authentication when sending the email uncomment the following
# two lines and set the username and password to be the correct ones
#$phpmailer_smtpuser = 'smtpuser';
#$phpmailer_smtppassword = 'smtppassword';

Temp dir

# tmpdir. A location where phplist can write some temporary files if necessary
# Make sure it is writable by your webserver user, and also check that you have
# open_basedir set to allow access to this directory. Linux users can leave it as it is.
# this directory is used for all kinds of things, mostly uploading of files (like in
# import), creating PDFs and more
$tmpdir = '/tmp';

Form action

# if you are on Windoze, and/or you are not using apache, in effect when you are getting
# "Method not allowed" errors you will want to uncomment this
# ie take off the #-character in the next line
# using this is not guaranteed to work, sorry. Easier to use Apache instead :-)
# $form_action = 'index.php';

Database module

# select the database module to use
# anyone wanting to submit other database modules is
# very welcome!
$database_module = "";


# you can store sessions in the database instead of the default place by assigning
# a tablename to this value. The table will be created and will not use any prefixes
# this only works when using mysql and only for administrator sessions
# $SessionTableName = "phplistsessions";


# there is now support for the use of ADOdb
# this is still experimental, and any findings should be reported in the
# bugtracker
# in order to use it, define the following settings:
#$database_module = '';
#$adodb_inc_file = '/path/to/adodb_inc.php';
#$adodb_driver = 'mysql';

Error level

For debugging purposes it could be useful to enable error reporting. Please consult the PHP documentation for more info on the constants to use for different error reporting levels, e.g. E_ALL would report all supported errors and warnings.

# if you want more trouble, make this 63 or E_ALL (very unlikely you will like the result)
$error_level = error_reporting(0);

Email address validation

Since v2.10.9 you can define the email validation level. For more, pleas see Validating email addresses.

# Since v2.10.9 you can define the email validation level. Possible values are:
# 0 = Disable email address validation.
# 1 = TLD & domain validation + no local part validation
# 2 = RFC821 email validation without escaping and quoting of local part
# 3 = RFC821 email validation [default value if this setting is undefined]

Page was generated in 1.0692 seconds