larger smaller normal text version of this page
phpList Documentation

Frequently Asked Questions - Installation and Configuration

This page hosts a list of FAQs, organized by topic. Please post general issues and bugs to Mantis Bug Tracker. Feel free to add your own questions, answers or both.


‹bersetzung Englisch Deutsch
‹bersetzung Spanisch Deutsch
‹bersetzung Deutsch Englisch

Problems installing phpList

  • How do I install phpList?
    • Please refer to the installation instructions in the Online Documentation Wiki, which are also available in the '/INSTALL' file in the distribution archive.
  • What server setup is required for running phpList?
  • I'm having problems during installation. Can anyone help me?
  • Where can I find the 'config.php' file?
    • Typically it's found in '/lists/config/config.php'. You need to have access to the files on your server (via FTP or SSH for example) to modify the config.php file. You cannot access it through your web browser.
  • What does 'Safe Mode On' mean?
    • 'Safe mode' is a feature in PHP versions prior to PHP 6. phpList works best with Safe mode disabled. It will also work in safe mode, with the exception of some features, that rely on functions in PHP that are not available in safe mode. phpList features that are not available in safe mode are automatic bounce processing, setting the timeout value of a page. Mailqueue batch size will also be limited. You can turn of all PHP warnings in phpList by setting the following configuration in config.php:
    • define ('WARN_ABOUT_PHP_SETTINGS',0);
  • Fatal Error: Cannot connect to database, access denied. Please contact the administrator
    • That error indicates something is wrong with your database connection details. A database connection requires four things, and they are very sensitive to errors (just one little typo and it won't work):
    • database host; the name of the server, usually it's 'localhost')
      database user; the name of the user on the database host
      database password; the password for that user
      database name; the name of the database to use
    • If any of these four are incorrect, you will get this error message. It's a good idea to double-check your settings, and confirm with your hosting provider or system administrator what the database connection details should be. Also, the database user must have full permissions on the database specified in the 'database name' setting.
  • Why does my website redirect to after I install phpList?
    • The file '/public_html/index.html' in the phpList distribution, says 'You will probably want to replace this document with your own website' and then redirects to In place of this file, you probably want to put your website's index.html file. In typical installations, you only need to upload the contents of the directory '/public_html/lists/' to your web server.
  • Can I run phpList on Microsoft IIS web webserver?
    • While phpList was primarily designed to work with Apache under unix-like systems (typically LAMP systems), users have managed to get it running with IIS. See PhplistIIS and the forums for details on how to do this.
  • My phpList installation has limitations on the amount of emails it can send
    • There are two main reasons for this to happen: Limitations of the sendmail program provided by your ISP, or that you are trying to process big queues directly from the browser.
    • If you use the sendmail engine provided by your ISP directly (no SMTP settings) you might have limitations on the amount of emails you can send. Due to security reasons ISPs might be reluctant to remove these limitations. So, if this happens to you the best route to take is to change the sendmail method to SMTP. This can be done by changing the phpList configuration in your config.php file.
    • To process the mail queue and keep sending emails, phpList needs to be able to keep running. There are several ways that phpList will use to keep the queue running even if you close the browser while processing the queue. However, depending on your ISP's configuration there is a possibility that none of them will work. If this happens to you, the solution is to process the mail queue by using a cron job. To setup a cron job please read: how to set a Cron Job
  • My SMTP server is not on the standard port 25. How do I change the default SMTP port?
    • This is currently not possible without a small modification of the code described in this report. After the modification you should be able to change the standard SMTP port by inserting this line in config.php: $phpmailer_smtpport = 'xxx'; (where xxx is the port number).
  • Why do I get a 500 Server Error?
    • If you get a '500 Server Error' when installing, your server probably runs PHP as a cgi, not as an apache module (also known as phpsuexec). You need to edit the file '/lists/.htaccess' delete or comment out (with a #) the line about 'php_flag magic_quotes_gpc'. e.g.
    # php_flag magic_quotes_gpc on
  • What does 'magic_quotes_gpc = on' mean?
    • Magic quotes is a PHP setting. If the server runs PHP as a cgi, you can turn magic quotes on by creating the file '/lists/php.ini' with this directive:
    magic_quotes_gpc = 1
    • More information about php settings in phpsuexec mode.
  • When I run the initialize process it shows me an error about index length: "database error 1071 - index length too long". Why is that?
    • If your hosting provider offers you an old version of MySQL (4.1.X or older), this error may arise because in old versions, indexes length has a byte limitation (1000 bytes). This error message will appear below a table name, and that table is the one that has the index length error. So, you will need to reduce the size of the field, or set of fields. The total length of it needs to be less that the 1000 bytes limit that MySQL imposes.

(More answers to common warning and error messages can be found on Troubleshooting).

Problems after installing phpList

  • Why does phpList ask me to login for every admin page I try to load?
    • This generally indicates that something is wrong with session handling in your PHP configuration. Check your php.ini file and make sure you have this set: session.use_cookies = 1, and/or ask your ISP to make sure sessions are enabled in your PHP configuration and are stored correctly.
    • The temporary directory on your server doesn't have read/write permissions. Please make sure that it does have read/write permissions.
    • The temporary directory has filled up with temporary files, and phpList is unable to write to it. You can fix this by cleaning up your temp dir.
    • You are connecting through multiple proxies and this means that your IP address isn't the same for every page request. (AOL is an example of an ISP that connects in this way.) You can solve this in config.php, by setting define("CHECK_SESSIONIP",0);
    • Alternatively, you can store sessions in the database instead of the default place by assigning a table name to this value. Enable this setting in config.php: $SessionTableName = "phplistsessions"; by uncommenting this line. The table will be created and will not use any prefixes. This only works when using mySQL and only for administrator sessions.
  • When loading the admin page I get some PHP code instead of a clean page. How do I fix this?
    • This issue is probably related to the use of 'short tags'. You should be able to fix this by adding the following line in the lists/.htaccess file: php_flag short_open_tag on
    • Alternatively, you could convert short tags to long tags by using the script included in the scripts directory of the phpList archive.
  • I just installed phpList, but sending my first messages fails. Why can't I send any message?
    • Please check if phpList is still running in Test mode. In config.php check your value for this constant (0 is off, 1 is on): define ("TEST",0); . See also Preflight Checklist.
    • When sending a 'test message' you should also check that your email address is included in the user list. If not, you will get this error message: "Email address not found to send test message".
    • It is recommended not to include links to Javascript files when sending an HTML email, since the receiving servers may quarantine or block it, due to consider it a a possible virus or unauthorised code.
    • If you are trying to send a message to a subscribers list, make sure you process the message queue. Otherwise your message will just be waiting in the queue.
    • If the above does not apply, it is likely something is wrong with your mail server settings. If you are using the PHP mail() function (which is the default setting in config.php), your host may have limited it's use. In that case you should contact your host to fix this. Alternatively, you could switch to using your SMTP server instead. To do so, edit the PHPMAILERHOST setting in your config.php file and enter your SMTP server name, e.g. define("PHPMAILERHOST",''); You will also need to enter your SMTP server's username and password by editing and uncommenting (i.e. by removing the # at the start of the line) the phpmailer_smtpuser and phpmailer_smtppassword settings in config.php. Usually the SMTP settings you would use in your email client should work here too. Note: If you use SMTP, make sure you apply this bug fix which is valid for phpList releases up to 2.10.5.
  • When I try to edit a message, or a message template, the part where the editing window should be is blank. How can I fix this?
    • This can occur when ASP tags are enable in php.ini. If you do not use ASP tags, you could set asp_tags = off in php.ini. For more information, see this issue report and this forum thread.
    • Alternatively, if you do not need an online editor, you can disable FCKeditor in your config.php file. The message content tab would then display a simple source window where you can paste your text and HTML source code.
  • My list has grown a little and now all my subscribers disappeared
    • When you reach a certain limit, phpList will stop listing your subscribers when you load the page. You will need to add some text in the search box to find the subscribers you are looking for. If you still want to see all you can search for % (just the percentage sign).
  • Why do I get messages twice?
    • In phpList versions 2.9.x and up, the "send test message" button will send you two messages, one in HTML and one in text format. This is so you can check how the messages look in both formats. Eventually, when you send your message, your subscribers will only receive one of the two formats, depending on their preferences.
    • Since version 2.10.3 you can override this behaviour, and only have one test message sent to you, by changing the default setting for "test emails" in config.php.
  • How do I mark everyone to receive HTML messages instead of text messages?
    • You can set all subscribers to receive HTML messages through the Admin backend: click on "manage users", then on "reconcile users" and finally on "mark all users to receive html". See Reconcile users.
  • How do I make my own subscribe pages?
    • In the spage (subscribe pages) area of phpList, you can create and edit subscribe pages. There you can edit the html of the header and footer, where you can insert html from your website's template. If you do not have any subscribe pages, you can edit the header and footer html from the phpList configuration area.
  • I've configured my own subscribe page and message texts on the Configuration page and they look OK there. But, when I subscribe a user all is back to the original defaults. Why is that?
    • You probably created a subscribe page before changing the settings on the configuration page. When you create a new subscribe page, it will take its initial settings from the defaults on the configuration page. Of course you can change these settings for each individual subscribe page you create. So, either create a new subscribe page, or copy/paste what you have on the configuration page to the corresponding fields in your existing subscribe page. See also Edit or create a subscribe page.
  • How do I place a subscribe form on an existing webpage?
  • How do I get rid of the 'powered by' image?
    • In the config.php file there is an option under the 'Feedback to developers' section that allows you to remove the phpList logo in the html emails and public web pages (including subscribe pages). You'll end up with just a text link giving credit to phpList and Tincan instead of the images.
  • Why do I lose all characters over 255 when I enter a long text in a textarea attribute?
    • The data entered into the textarea is stored in the database. To prevent the database from becoming big and slow this is done using a 'varchar', which has a 255 characters limit. If you do want to use a bigger textarea attribute look for the solution in the forums. It has been done before: here is one solution and this has some more explanation. The code support it.
  • The links in the confirmation messages are misformed or have no UID code. How can I fix this?
    • You can fix this by changing the message encoding setting for text messages in config.php. Usually 7bit encoding is a good setting, i.e.: define("TEXTEMAIL_ENCODING","7bit");
  • How can I make a backup copy of my user list and other important data?
    • phpList's admin module currently only offers an option to export the user lists. An option to make a backup of the entire phpList database is scheduled for a future release. In the mean time it is highly recommended to regularly make a full backup of your phpList database using a tool like phpMyAdmin for instance.
  • Are there any security fixes I should be aware of?
    • Security announcements can be found on the phpList News page. We recommend you subscribe to the phpList Newsletter, so we can keep you up to date on any new security announcement, upcoming phpList releases, and changes in the documentation.

  • I'm using Gmail as a bounce account. When I process bounces mails remain on the inbox... Did I setup something wrong?
    • First thing to check is the bounce_mailbox_purge configuration. But even with that set correctly when Gmail is using POP3 (by default) it keeps mails on the inbox. So even with phpList configured to purge, it won't purge. To solve this you'll need to:
      • In Gmail go to: Settings -> Forwarding and POP -> When messages are accessed with POP...
      • As default Gmail has: "Keep Gmail's copy in the inbox" you'll need to change this to: "Delete Gmail's copy".

Translation and Internationalization (i18n)

  • I am using another language file than, but some text strings keep appearing in English. Why is that?
    • 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. You can fix this by adding the missing text strings in your language file. Also search the Translators & Internationalization forum. Updated translations may already be available there. Note: If you are thinking about translating, please see the phpList translation page.
  • phplist scrambles my text messages. How do I fix this?
    • In versions before 2.10.3 phpList had some trouble converting multi-lingual messages from HTML to text. In most cases, this caused HTML characters like & eacute; to appear in the text versions of the messages. In version 2.10.3 this has been addressed, but it will be important to set your encoding of HTML and text messages to be UTF-8 instead of the default ISO-8859-1 . To do so, go to "configure" on the menu and scroll down to "Charset for HTML messages" and "Charset for text messages" and set both values to be "UTF-8".
    • phplist will try to interpret html tags. If you write a mathematical thesis to you list users it might catch a '<' and a '>' in the same line and remove the part in between. To avoid this, use < and >
    • <> will not be handled correctly. Use this instead:
      <a href="">nicename</a>
  • When will Wikka support other languages/utf-8 ?
    • phplist supports limited internationalization at the moment, but complete internationalization is currently being implemented.

Related topics
Page was generated in 0.0907 seconds