PhpList

   phpList

Notes about configuration phpList Mailing List software with bounce processing.

About phpList

 * Website — www.phplist.com
 * Documenation — docs.phplist.com
 * Forum — forums.phplist.com
 * See post — Getting phpList working with a cPanel cron job.
 * Download — www.phplist.com/download

Features

 * Web-based Mailing List (email announcement) management software with bounce processing.

Installation & Configuration
Instructions for installing phpList including post-install configuration.

Installing phpList
Installing phpList with cPanel Fantastico auto installer.
 * 1) Login to cPanel and load the Fantastico page.
 * 2) Select phpList and click the New Installation link.
 * 3) Set the Installation Location: Domain and Folder.
 * 4) Enter the Administrator's Account: Username, Password and E-mail.
 * 5) Enter the Base Configuration: Bounces=5, Lists=5, Criterias=2, Attachments=2, Language=English.
 * 6) Enter the Email Account Configuration (for bounce processing):
 * 7) * E-mail account username — phplist@yourdomain.com
 * 8) * E-mail account password — yourpassword
 * 9) * POP/SMTP server — mail.yourdomain.com
 * 10) Set the Message Queue Processing to Manual or Cron for auto-processing. See  below.
 * 11) Complete the installation, remembering to email the configuration settings to yourself.
 * 12) Logout of cPanel, then Login to phpList to finish the configuration.

Setting phpList Cron via cPanel
/usr/local/bin/php -q /home/yourdomain/public_html/phplist/admin/index.php -p processqueue -c /home/yourdomain/public_html/phplist/config/config.php > /home/yourdomain/cronoutput.txt
 * 1) Login to cPanel
 * 2) Click on the Advanced > Cron Jobs button.
 * 3) Click on the Standard experience level button.
 * 4) Set the cron job to run Every Fifteen Minutes, Hour, Day, Month and Week Day.
 * 5) Insert the cron job code (adding code to output a text file of the results:

Set Configuration Settings
Setting the primary configuration values (see below for email and template settings).
 * 1) Login to phpList Admin at http://www.yourdomain.com/phplist/admin/
 * 2) Select configure from the right menu to load the configure phplist page.
 * 3) Verify that the primary configuration values are correct, paying particular attention to:
 * 4) * Set Website address to yourdomain.com -or- www.yourdomain.com.
 * 5) * Set Domain Name of server (for email) to yourdomain.com. This is added to email addresses with the  placeholder value.
 * 6) * Set Who gets the reports to you@yourdomain.com -or- you@[DOMAIN].
 * 7) * Set From email address for system messages to info@yourdomain.com This should NOT be the same as the bounce address. You should check this account for user replies.
 * 8) * Set System Messages Name to Mailing List Name.
 * 9) * Ensure Reply-to email address for system messages is noreply@yourdomain.com.
 * 10) * At the bottom of the configuration page, set Domains that only accept text emails to (space) — remove the mail.com and email.com values.
 * 11) Click Save Changes.

Configure Attributes
Setting up Attributes which add fields for subscribed users.
 * 1) On the Main Admin page, click on System Functions > setup.
 * 2) On the Configuration Options page, click on Configure Attributes to add any additional fields you want.
 * 3) Add field Name, type textline, default value novalue, required ticked.
 * 4) Click Save Changes.

Create Lists
Setting up the List(s).
 * 1) On the Main Admin page, click on System Functions > setup.
 * 2) On the Configuration Options page, click on Create Lists to configure the list.
 * 3) * Click on the edit link to setup the default list 1.
 * 4) * Set the List Name to Fishcakes Test List; Tick the Make List Active box; and enter a List Description.
 * 5) Click Save.

Configure the Subscribe Emails
Enter the Subject and Message text as follows:
 * 1) Select configure from the right menu to load the configure phplist page.
 * 2) Confirmation Request — set the Subscribe message subject and text.
 * 3) * NOTE: this Confirmation request is over-ridden by the Subscribe Pages values below.
 * 4) Unsubscribe — set the Unsubscribe message subject and text.
 * 5) Welcome — set the Message received after confirming subject and text.
 * 6) * NOTE: this Welcome message is over-ridden by the Subscribe Pages values below.
 * 7) Preferences Updated — Set the Message received when details changed subject and text.
 * 8) * Set the NEW email address part text and the OLD email address part text (prefs update email).
 * 9) * BUG WARNING: This message cannot contain ' (apostrophe) characters!
 * 10) Preferences Page Request — set the Subject and Message for personal location request subject and text.
 * 11) * BUG WARNING: This message cannot contain ' (apostrophe) characters!
 * 12) Footer — set for all messages.
 * 13) * Make sure your HTML Email Template includes the  placeholder or the formatting will be ruined when this is added to the end.
 * 14) Forward Footer — set for all messages.
 * 15) * This appears where the HTML Email  placeholder is located, or just added to the end of a text message.
 * 16) Click Save Changes.
 * NOTE: See phpList Docs: Placeholders for list of datbase fields you can insert into the messages.

Configure the Web Template
Enter the default Header and Footer for your web pages.
 * 1) Select configure from the right menu to load the configure phplist page.
 * 2) Paste the HTML code for the Header of public pages field.
 * 3) Paste the HTML code for the Footer of public pages field.
 * 4) Click Save Changes.
 * NOTE: these values are over-ridden by the Subscribe Pages below.

Create Subscribe Pages
You should also create a Subscribe Page for your mailing list, which allows you to control which fields are displayed to the user.
 * 1) Select subscribe pages from the right menu to load the subscribe pages page.
 * 2) Click on the add a new one link, or the edit link for an existing page, to load the edit a subscribe page.
 * 3) Fill in the details for the list subscription pages and emails.
 * 4) * Title — this is only used internally.
 * 5) * Language — should usually be default.
 * 6) * Intro — this text appears at the top of the subscribe page.
 * 7) * Header — this over-rides the HTML Header on the main configuration page.
 * 8) * Footer — this over-rides the HTML Footer on the main configuration page.
 * 9) * Thank You — displayed after a user hit's the subscribe button. Should include info about checking Bulk Mail folder for web-based services.
 * 10) * Button text — something like Subscribe to mailing list.
 * 11) * HTML Choice — select the Don't offer choice, default to HTML button.
 * 12) * Email Confirmation — select the Don't display email confirmation button.
 * 13) * Set the Subject and Subscribe message text (confirmation request).
 * 14) ** NOTE: this Confirmation message over-rides the main configuration page value.
 * 15) * Set the Subject and Message received after confirming (welcome email).
 * 16) ** NOTE: this Welcome message over-rides the main configuration page value.
 * 17) * Attributes — enable all the fields you want users to fill in when subscribing
 * 18) * Select Lists — tick all the lists you want to offer.
 * 19) Click Save and Activate then preview the page.

Edit Config File
You now need to edit the file.
 * 1) Set the Message Envelope for bounces to return to. Uncomment and change Line 69 to:
 * $message_envelope = 'list-bounces@yourdomain.com';
 * 1) Specify the Pop account. Edit lines 82 to 84:
 * $bounce_mailbox_host = 'mail.yourdomain.com';
 * $bounce_mailbox_user = 'list-bounces@yourdomain.com';
 * $bounce_mailbox_password = 'yourpassword';
 * 1) Enable User Passwords and require password for unsubscribe. Edit line 143 and line 148:
 * define("ASKFORPASSWORD",1);
 * define("UNSUBSCRIBE_REQUIRES_PASSWORD",1);
 * 1) Remove phpList image from HTML emails. Edit line 267:
 * define("EMAILTEXTCREDITS",1);
 * 1) Remove phpList image from Web pages. Edit line 271:
 * define("PAGETEXTCREDITS",1);
 * 1) Set the Mail Queue settings to match your mail server. Set the server to send out 300 messages per hour, spaced at one every 10 to 12 seconds.
 * 2) * Set number of emails to send per period. Edit line 312:
 * define("MAILQUEUE_BATCH_SIZE",300);
 * 1) * Ensure length of one batch processing period, in seconds (3600 is an hour). Check that line 315 is set to:
 * define("MAILQUEUE_BATCH_PERIOD",3600);
 * 1) * Set mail queue throttle limit to space out messages (in seconds). Edit line 321:
 * define('MAILQUEUE_THROTTLE',10);
 * 1) Set the From message to be from List email address, not User email address. Edit line 346:
 * define('USE_ADMIN_DETAILS_FOR_MESSAGES',0);
 * 1) Set test email to send only 1 test email. Edit line 353:
 * define('SEND_ONE_TESTMAIL',1);
 * 1) Use SMTP authentication. Uncomment and edit lines 625 to 626:
 * #$phpmailer_smtpuser = 'list-bounces@yourdomain.com';
 * #$phpmailer_smtppassword = 'yourpassword';
 * 1) Save the file.

Creating the Web Template

 * tbd

HTML Email Template
Details of how to create a Multipart/Alternative MIME email which will display in most email clients as well as webmail services.

Creating the HTML Email Template

 * css — use inline CSS or HTML FONT tags as most CSS styles and all CSS structure elements will be stripped.
 * images — use only HTML embeded images and CSS url embeded images don't always load.
 * structure — use table based layout as CSS divs don't always work.
 * width — keep it as narrow as possible as wide just doesn't work. AOL has max width of 200px!
 * headers — browser-based email services (Google, Yahoo, Hotmail...) will strip out your DOCTYPE, BODY, and HEAD tags. Anything inside those tags will get stripped.
 * email client testing — test for AOL (Desktop), Apple Mail, Entourage, Eudora, Lotus, Outlook, Outlook 2003, Outlook 2007, Outlook Express, Thunderbird.
 * webmail testing — test in Firefox, Internet Explorer (IE), Netscape, Opera and Safari on Mac and Windows for these browser-based services: AOL Webmail, Comcast, Earthlink, Google, Hotmail, MSN, Yahoo!Mail.

Configuring the HTML Email Template
tbd

Message Subject
Subjects for email messages should be no more than 60 characters (including spaces) maximum or they may be truncated by some email clients. Our Mailing List: What a Lovely Day Show - Tue 18 Jan 2008    <- title of message 123456789012345678901234567890123456789012345678901234567890  <- character count >1>2>3>4>5>6  <- 60 characters maximum

Verifying Emails
In order to verify that your message are getting through to end users, you should setup and subscribe test accounts for the following major providers:
 * Excite.com or Excite.co.uk
 * GoogleMail.com
 * Hotmail.com or MSN.com
 * Mail.com
 * Yahoo.com or Yahoo.co.uk

Plugins & Hacks
Plugins and Hacks to extend the functionality of PhpList. See Add-ons, Contributions, Mods, Plug-ins forum thread.

Activate Plugins
Before you can use any plugins, you must first active plugins for your PhpList installation:
 * 1) Edit the file.
 * 2) Change line 572 from (uncomment it):
 * # define("PLUGIN_ROOTDIR","plugins");
 * To:
 * define("PLUGIN_ROOTDIR","plugins");
 * 1) Change line 568 from (comment it out):
 * define("PLUGIN_ROOTDIR","/home/me/phplistplugins");
 * To:
 * #define("PLUGIN_ROOTDIR","/home/me/phplistplugins");

Display message open statistics
Gives opened and bounce stats for individual users for each HTML message (as far as it's possible to tell). See forums.phplist.com/viewtopic.php?p=10108#10108.

To install:
 * 1) Ensure your PhpList installation has plugins enabled (see above).
 * 2) Upload the folder   and the file   to the   folder of your PhpList installation.
 * 3) Click on the statistic menu item which is now in your right hand admin panel.
 * 4) Click on the open statistics by message link to
 * 5) Enter a message ID number to view the stats.

Multiple Content Areas
The plugin PBTS_XTRA adds Multiple Content Areas to phpList. See Mulitple Content Areas in Template forum thread or PBTS Extra Overview developer's website.

To install: if ($cached[$messageid]["template"]) # template used $htmlmessage = eregi_replace("\[CONTENT\]",$htmlcontent,$cached[$messageid]["template"]); else { to: if ($cached[$messageid]["template"]){ # template used if (!preg_match("/\[PBTS_/is", $cached[$messageid]["template"])) $htmlmessage = eregi_replace("\[CONTENT\]", $htmlcontent, $cached[$messageid]["template"]); else $htmlmessage = pbts_replace_content( $htmlcontent, $cached[$messageid]["template"] ); } else {
 * 1) Edit the file   and the file   to your   folder.
 * 2) Edit the file   BACKUP YOUR FILE BEFORE PROCEEDING:
 * 3) Add this line to the top of the file:
 * include_once dirname(__FILE__).'/plugins/pbts_xtra/pbts_xtra.inc.php';
 * 1) Replace the current Template tag substitution with the PBTS_XTRA calls by changing: