PhpList

From Fishcakes Wiki

phpList

Notes about configuration phpList Mailing List software with bounce processing.

Contents 1 About phpList 1.1 Features 1.2 See Also 2 Installation & Configuration 2.1 Installing phpList 2.2 Setting phpList Cron via cPanel 2.3 Set Configuration Settings 2.4 Configure Attributes 2.5 Create Lists 2.6 Configure the Subscribe Emails 2.7 Configure the Web Template 2.8 Create Subscribe Pages 2.9 Edit Config File 3 Web Template 3.1 Creating the Web Template 3.2 Configuring the Web Template 4 HTML Email Template 4.1 Creating the HTML Email Template 4.2 Configuring the HTML Email Template 4.3 See Also 5 Sending a Message 5.1 Message Subject 5.2 Verifying Emails 6 Plugins & Hacks 6.1 Activate Plugins 6.2 Display message open statistics 6.3 Multiple Content Areas

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.

See Also

• tbd

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):
   • E-mail account username — phplist@yourdomain.com
   • E-mail account password — yourpassword
   • POP/SMTP server — mail.yourdomain.com
7. Set the Message Queue Processing to Manual or Cron for auto-processing. See below.
8. Complete the installation, remembering to email the configuration settings to yourself.
9. Logout of cPanel, then Login to phpList to finish the configuration.

Setting phpList Cron via cPanel

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:

/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

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:
   • Set Website address to yourdomain.com -or- www.yourdomain.com.
   • Set Domain Name of server (for email) to yourdomain.com. This is added to email addresses with the [DOMAIN] placeholder value.
   • Set Who gets the reports to you@yourdomain.com -or- you@[DOMAIN].
   • 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.
   • Set System Messages Name to Mailing List Name.
   • Ensure Reply-to email address for system messages is noreply@yourdomain.com.
   • At the bottom of the configuration page, set Domains that only accept text emails to (space) — remove the mail.com and email.com values.
4. 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.
   • Click on the edit link to setup the default list 1.
   • Set the List Name to Fishcakes Test List; Tick the Make List Active box; and enter a List Description.
3. 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.
   • NOTE: this Confirmation request is over-ridden by the Subscribe Pages values below.
3. Unsubscribe — set the Unsubscribe message subject and text.
4. Welcome — set the Message received after confirming subject and text.
   • NOTE: this Welcome message is over-ridden by the Subscribe Pages values below.
5. Preferences Updated — Set the Message received when details changed subject and text.
   • Set the NEW email address part text and the OLD email address part text (prefs update email).
   • BUG WARNING: This message cannot contain ' (apostrophe) characters!
6. Preferences Page Request — set the Subject and Message for personal location request subject and text.
   • BUG WARNING: This message cannot contain ' (apostrophe) characters!
7. Footer — set for all messages.
   • Make sure your HTML Email Template includes the [FOOTER] placeholder or the formatting will be ruined when this is added to the end.
8. Forward Footer — set for all messages.
   • This appears where the HTML Email [FOOTER] placeholder is located, or just added to the end of a text message.
9. 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.
   • Title — this is only used internally.
   • Language — should usually be default.
   • Intro — this text appears at the top of the subscribe page.
   • Header — this over-rides the HTML Header on the main configuration page.
   • Footer — this over-rides the HTML Footer on the main configuration page.
   • Thank You — displayed after a user hit's the subscribe button. Should include info about checking Bulk Mail folder for web-based services.
   • Button text — something like Subscribe to mailing list.
   • HTML Choice — select the Don't offer choice, default to HTML button.
   • Email Confirmation — select the Don't display email confirmation button.
   • Set the Subject and Subscribe message text (confirmation request).
     • NOTE: this Confirmation message over-rides the main configuration page value.
   • Set the Subject and Message received after confirming (welcome email).
     • NOTE: this Welcome message over-rides the main configuration page value.
   • Attributes — enable all the fields you want users to fill in when subscribing
   • Select Lists — tick all the lists you want to offer.
4. Click Save and Activate then preview the page.

Edit Config File

You now need to edit the file phplist/config/config.php.

1. Set the Message Envelope for bounces to return to. Uncomment and change Line 69 to:

   $message_envelope = 'list-bounces@yourdomain.com';

2. 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';

3. Enable User Passwords and require password for unsubscribe. Edit line 143 and line 148:

   define("ASKFORPASSWORD",1);

   define("UNSUBSCRIBE_REQUIRES_PASSWORD",1);

4. Remove phpList image from HTML emails. Edit line 267:

   define("EMAILTEXTCREDITS",1);

5. Remove phpList image from Web pages. Edit line 271:

   define("PAGETEXTCREDITS",1);

6. 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.
   • Set number of emails to send per period. Edit line 312:

   define("MAILQUEUE_BATCH_SIZE",300);

   • 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);

   • Set mail queue throttle limit to space out messages (in seconds). Edit line 321:

   define('MAILQUEUE_THROTTLE',10);

7. Set the From message to be from List email address, not User email address. Edit line 346:

   define('USE_ADMIN_DETAILS_FOR_MESSAGES',0);

8. Set test email to send only 1 test email. Edit line 353:

   define('SEND_ONE_TESTMAIL',1);

9. Use SMTP authentication. Uncomment and edit lines 625 to 626:

   #$phpmailer_smtpuser = 'list-bounces@yourdomain.com';

   #$phpmailer_smtppassword = 'yourpassword';

10. Save the file.

Web Template

Creating the Web Template

• tbd

Configuring the Web Template

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

See Also

• CanSpam — requirements for Commercial Emailers.
• mailchimp.com — bulk email service provider with good tutorials.

• How Spam Filters Think.
• HTML Email Tips for Web Designers.

• Constant Contact — bulk email service provider.
• iContact — bulk email service provider.
• MyEmma — bulk email service provider.

Sending a Message

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 config/config.php.
2. Change line 572 from (uncomment it):

   # define("PLUGIN_ROOTDIR","plugins");

   To:

   define("PLUGIN_ROOTDIR","plugins");

3. 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 statistics and the file statistics.php to the admin/plugin/ 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:

1. Edit the file config/config.php<code>:
   1. Turn off the WSYSIWYG editors via a configuration setting (~line 481):

      define("USEFCK",0);

   2. Turn off the TinyMCE editors:

      define("USETINYMCETEMPL",0);

   3. Turn off the auto-generated text email box:

      define("USE_MANUAL_TEXT_PART",1);

2. Enable your Plugin directory (see above)
3. Upload the folder <code>pbts_xtra and the file pbts_xtra.php to your admin/plugins/ folder.
4. Edit the file admin/sendemaillib.php BACKUP YOUR FILE BEFORE PROCEEDING:
   1. Add this line to the top of the file:

      include_once dirname(__FILE__).'/plugins/pbts_xtra/pbts_xtra.inc.php';

   2. Replace the current Template tag substitution with the PBTS_XTRA calls by changing:

  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 {