USING PHPLIST TO MANAGE AND SEND BULK EMAIL CAMPAIGNS - Jan 26th, 2019


As more and more ISPs clamp down on the rules for sending bulk emails, making sure that an email campaign is delivered
to multiple recipients has become more of a challenge.

I've been successfully using the open source PHPList
https://www.phplist.org/download-phplist/
to handle the job.

The only downside is that if you are currently managing captured email addresses using CMS Builder you'll have to paste
any email lists and remove request lists from CMSB into PHPList, but that is a really quick procedure.

Or, if it works for you, you can let PHPList handle the whole process of capturing email addresses and remove requests
automatically

PHPList also does a commendable job of sending either web pages or WYSIWYG documents to recipients as emails, bounced
email management, click tracking for links, and it has many other features.

In fact, all the email management features that we've asked for on the forum seem to be incorporated into PHPlist, and
it's free and open source.

Below is a set of instructions on how to set up and use use PHPList together with cron jobs to handle automatic
scheduling of both single, and automatically repeated email campaigns (great for things like monthly newsletters).

That's followed by some User Level help documentation
___

(ADMIN -PROGRAMMERS) SETTING UP PHPLIST FOR CAMPAIGN EXECUTION AND BOUNCED MANAGEMENT USING CRON JOBS

Step 1 through 4 are changes to the basic config.php file, step 5 and 6 are about setting up the cron jobs, Step 7
setting up your listbounces@your_domain.com mailbox Step 8 is about testing the result.

Step 1) Since My Web Host limits the amount of emails sent in one hour to 150, and allowing 25 for possible overhead,
125 per hour can safely be sent, so set the:

MAILQUEUE_BATCH_SIZE to 125 - 125 messages per batch,
MAILQUEUE_BATCH_PERIOD to 3600 - 1 batch per hour,
MAILQUEUE_THROTTLE to 1 - one second between messages,
MAILQUEUE_AUTOTHROTTLE - to 0 (off ).
(Don’t add these to the config file now, they'll be added in step 3)

Step 2) set define MANUALLY_PROCESS_QUEUE to 0 (off)

Step 3) Add the following to the config.php file (no values need to be changed for 125 emails per batch)

define ("MANUALLY_PROCESS_QUEUE",0);
define('MAX_PROCESS_MESSAGE',999);
define("MAILQUEUE_BATCH_SIZE",125);
define("MAILQUEUE_BATCH_PERIOD",3600);
define('MAILQUEUE_THROTTLE',1);
define('MAILQUEUE_AUTOTHROTTLE',0);
define('USE_DOMAIN_THROTTLE',0);
define('DOMAIN_BATCH_SIZE',1);
define('DOMAIN_BATCH_PERIOD',120);
define('DOMAIN_AUTO_THROTTLE',0);
define('MAX_PROCESSQUEUE_TIME',0);
define("PLUGIN_ROOTDIR","/path-to-your/phplistplugins");

NOTE: Plugins are in the phplistplugins directory

Step 4) To handle automatic processing of bounced emails, uncomment the:
$message_envelope = 'listbounces@your_domain.com';

Set the:
define MANUALLY_PROCESS_BOUNCES to 0 (off),
$bounce_mailbox_host = 'localhost'; to the actual incoming mailserver address: (mail.your_domain.com)
$bounce_mailbox_user = 'popuser'; to the actual email username: (listbounces@your_domain.com)
$bounce_mailbox_password = 'password'; (SoMePasSwoRD is entered here).

Step 5) Set up a cron job for processing cued campaigns:

/usr/bin/php-cli -q /path-to-your-installation/lists/admin/index.php -p processqueue -c
/path-to-your-installation/lists/config/config.php

Set the repeat execution time value to every few minutes for testing, and then to a reasonable for the campaign density.

Step 6) Set up a Cron job to handle bounced emails (Your path may be different then the sample code) Look at
CMSB>Admin>Background Tasks for a path specific to your server:

/usr/bin/php-cli -q path-to-your-installation/lists/admin/index.php -p processbounces -c
/path-to-your-installation/lists/config/config.php

Again, set the repeat execution time value to every few minutes for testing, and then to once per hour.

Step 7) Setting up a listbounces@your_domain.com mailbox:

Email Accounts in the your cPanel, add a mailbox called listbounces@your_domain.com with the password: SoMePasSwoRD (or
one of your choosing)

Step 8) Testing

Add your email to the cron job reporting so that you see the results of any tests.

Create a test campaign with a few email addresses that you control.

Complete all the steps required to send a campaign but, if you’ve previously sent campaigns manually, you notice that
there is no longer a “process queue” button to click, because the cron job will start sending your campaign
automatically.

Once the process is working correctly it is no longer necessary to keep the browser window open or even to keep the
computer on to send a campaign or process bounces.

Once all is working as it should, you can reset the cron job execution times to a more reasonable frequency (once per
hour) and remove your email address from the cron job reporting. >/dev/null 2>&1 can also be added to the end of the
cron command line to prohibit sending reporting emails for specific cron jobs.

Issues? Email Dan Waterloo at dan@phplistsupport.com (phplistsupport.com is a private company and is not a free service)
___

SETTING UP AND USING THE USE_REPETITION FUNCTION TO SCHEDULE THE AUTOMATIC RE-SENDING OF THE SAME CAMPAIGN TO THE SAME
SUBSCRIBER LIST.
(Great for sending a web page with dynamic content like a newsletter, weekly specials, etc.)

Enabling the option to re-send the same campaign in the future is as simple as adding define('USE_REPETITION',1); to
your config.php file.

Once enabled, when you create a new campaign, 2 new fields will be added to the scheduling tab, “Repeat Campaign
Every” and “Repeat Until”.

When these are set, and the campaign is sent (or cued if you’re using a cron job), PHPList will automatically create a
new message with the same content using those repetition settings. The embargo of the message will be automatically
increased to accommodate the repetition settings you choose.

If you are using a cron job to automatically trigger the sending of cued campaigns, the campaign will be not be sent
more often than the repetition rate set in the “Repeat Campaign Every” setting of that campaign.

NOTE: If you go back to edit your campaign in any way, it will be considered a “draft” and will not be automatically
sent until it has been re-cued or re-sent.

*Exclusion of times and dates*

You can globally tell PHPList NOT to send (ie re-schedule) messages at certain times, like weekends or holidays by
adding the following code to your config.php file.

# exclude dates for repetition
$repeat_exclude = array(
array("format" => "%a", "values" => array("Sun","Sat")),
array("format" => "%d-%m-%Y","values" => array("31-01-2004","01-01-2005")),
);
## end
You can add as many entries as you like using the following format:

array("format" => [format], "values" => array([list of values])),

The bits between [ and ] can be chosen as you like it, but they have to conform to the following rules:

[format] needs to be a Mysql data format string. There’s more information at:

http://dev.mysql.com/doc/refman/5.0/en/date-and-time-functions.html#function_date-format

[list of values] needs to be a list of values that this format can return, which then, if matched with the new
“embargo” for a message will not create a message for that date, but instead increases the “repetition value” to
find the next one in a row.

So for example for excluding the weekend you use array(“format” ? ”%a”, “values” ?
array(“Sun”,”Sat”)), and for excluding specific dates you can use array(“format” ?
”%d-%m-%Y”,”values” ? array(“31-01-2004”,”28-08-2004”)),

___

USER INSTRUCTIONS:

USING PHPLIST TO SEND OUT EMAIL CAMPAIGNS

PHPlist allows you to send out large numbers of emails at one time.

A) Open <a target="_blank"
href="http://www.your_domain.com/your-email-list.php"><u>http://www.your_domain.com/your-email-list.php</u></a> and copy
the desired list of email addresses. (CTL-C)

B) Log in to the PHPList admin page at:


<a target="_blank" href="http://www.your_domain.com/lists/admin/"><u>http://www.your_domain.com/lists/admin/</u></a>


1) From the subscriber menu, choose “Subscriber Lists”
2) Click on the little garbage can icon to delete the existing “Salon” list
3) Add a new list called “Salon” and Save
4) Click on “Add Some Subscribers”
5) Paste the copied list (CTL-P) into the empty box and click on “Import Emails”
6) Either “Import Some More Emails” (add your email address to the list) if required, or
7) Choose "Send a Campaign” from the" Campaigns" menu, and click on "Start a New Campaign"
8) Fill in the “Subject” and the “From” Field
9) Check the “Send a Web Page” button and fill in the URL of the E-Blast Web Page
10) Delete any code in the “Footer” box, click “Next”
11) Leave HTML checked and fill in your email address in the “Send Test” box and click on “Send Test”
12) If the test is received and all is well, click “NEXT”, decide when to send the campaign (or leave the defaults
to send immediately) and click “NEXT” again.
NOTE: If you want to automatically repeat sending this particular campaign (I.E. A Monthly Newsletter) you would select
"every 4 weeks" from the “Repeat Campaign Every” field and as far in the future as required from the “Repeat
Until” field. This specific campaign will automatically be repeatedly sent based on the parameters you enter.
13) Select the list to send to (Salon) and click “NEXT”
14) Check the “Reset Click Statistics” box and click “Send Campaign”. The campaign will automatically start
processing at the top of the next hour.

NOTE: You can safely close your browser and/or turn off your computer after you've finished step 14. You will receive a
number of progress emails to let you know the start and end of the mailing process.

*** AFTER A SPECIFIC REPEATING CAMPAIGN HAS BEEN SENT THE FIRST TIME, <u>DO NOT</u> DELETE THE EMAIL LIST ASSOCIATED
WITH THAT CAMPAIGN.

INSTEAD, FOLLOW THE STEPS IN "ADDING SUBSCRIBERS TO A PHPLIST EMAIL LIST" TO UPDATE THE ASSOCIATED EMAIL LIST.

YOU DO NOT NEED TO CREATE THAT NEW SPECIFIC REPEATING CAMPAIGN AGAIN***

NOTE: "Click Tracking" is enabled for your campaigns. This means that you can view detailed statistics about which links
in a campaign email have been clicked on by each of the email recipients.

WARNING: When managing campaigns, if you delete a "sent" campaign, the campaign's click tracking data will also be
deleted, and links in the campaign emails will no longer work.

There's more information at: http://www.phplist.com/support
___

ADDING SUBSCRIBERS TO A PHPLIST EMAIL LIST

After you've created a master email list or have sent out a repeating campaign for the first time, you only need to add
email addresses in the email list.

***NEVER DELETE AN EMAIL LIST THAT IS USED IN A REPEATING CAMPAIGN***

TO ADD NEW EMAIL ADDRESSES TO AN EMAIL LIST:

A) Open <a target="_blank"
href="http://www.your_domain.com/your-email-list.php"><u>http://www.your_domain.com/your-email-list.php</u></a> and copy
the desired list of email addresses. (CTL-C or CMD-C)

B) Log in to the PHPList admin page at:


<a target="_blank" href="http://www.your_domain.com/lists/admin/"><u>http://www.your_domain.com/lists/admin/</u></a>


1) From the subscriber menu, choose “Import Emails”
2) Check the check box for the appropriate list
3) Check the “skip email addresses that are not valid” check box
3) Paste the copied list (CTL-P or CMD-P) into the empty box.
4) Click on "Import Emails".
4) Your new emails will be added to the list and will automatically receive the repeating campaign, you can now close
your browser tab.
___

DELETING SUBSCRIBERS FROM ALL PHPLIST EMAIL LISTS

There are times when a subscriber will want to opt out of receiving email blasts and newsletters from you and they exist
on a list that you are not allowed to delete (like a repeating NEWSLETTER list).

To remove subscribers.

A) Open


http://www.your_domain.com/your-email-list.php


and copy the list of email addresses to be removed. (CTL-C or CMD-C)

B) Log in to the PHPList admin page at:


<a target="_blank" href="http://www.your_domain.com/lists/admin/"><u>http://www.your_domain.com/lists/admin/</u></a>


1) From the "Subscriber" menu choose "suppression list"
2) *** Un-check the "make suppression permanent" checkbox***
3) Paste the email addresses in the empty box (CTL-P or CMD-P)
4) Click Continue

That's it, your done. Any duplicates will be ignored

NOTE: If you don't un-check the "make suppression permanent" you will cause the subscriber to be blacklisted on
PHPList, and that adds another step to reinstating them if ever required.

Added Jan, 25, 2019: If your campaigns don't seem to be sent out as planned, check the scheduling tab and the embargoed
until field. If it is not set to the top of the current hour then you may have a server time issue. You can install the
timezone plugin to correct the time difference. It'a available from the clone or download button at:
https://github.com/bramley/phplist-plugin-timezone



The materials on this web site have been created for use with CMS Builder content management software. CMS Builder software is published and licensed for use by InteractiveTools.com. Please contact Interactive Tools for information on the downloading of the software or the purchasing of licenses.


Terms of Service