PhpList Php List Manual Web 20150629

phpList_manual_web_20150629

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 218

DownloadPhpList Php List Manual Web 20150629
Open PDF In BrowserView PDF
PHPLIST

1

Published : 2015-06-29
License : CC-BY-SA

2

INTRODUCTION
1. SYSTEM OVERVIEW
2. CASE STUDIES
3. ABOUT THIS MANUAL

3

1. SYSTEM OVERVIEW
Welcome to the phpList Manual.
This first chapter will explain what phpList is used for and give you a
basic overview of how it works.

WHAT IS PHPLIST?
phpList is used for sending email newsletters, announcements and
notifications. It is designed to send a single message (a campaign),
by email to large numbers of recipients (subscribers).
You organise your subscribers into lists and you can import email
addresses from your email account, online shop, blog or database.
You can also import attribute data, for example, subscriber name,
city or shoe size.
Campaigns are composed in a web interface and can be
personalised for each subscriber. Personalisation is done with the
use of placeholders which display attribute data within the text of the
emails, as well as unique links that allow subscribers to join or
leave lists easily. You can use plain text, HTML and templates.
Once a campaign has been sent, phpList will show statistics about it.
This will include opens/views (who read the campaign), clicks (who
clicked which link in the campaign) and bounces (which addresses
were incorrect and delivery failed). Bounced mails and unsubscribes
are automatically removed from the system, which will benefit future
delivery of campaigns.
phpList is Open Source software and it is published under the AGPLv3
licence. You can install and host phpList on your own servers or
you can use it via the phpList Hosted service.

A QUICK TOUR OF PHPLIST
phpList has an attractive web interface and a wealth of features to
explore.

Campaigns
Composing and sending campaigns is achieved by following a step by
step process.

4

Subscribers
In phpList you upload your contacts once and the information is ready
to use every time you send a campaign.

You can group subscribers into one or more lists

5

Simply choose which list you want to send to when you create your
campaign.

6

Subscribe pages
Subscribers can sign up to your lists though subscribe pages, which
are fully customisable.

...and can be integrated with your website.

7

Campaign Statistics
You can view basic and detailed statistics about every campaign you
send to help you learn more about your subscribers.

WHAT IS OPEN SOURCE?
Open Source, or "Free Software", means that the original
programming code is made freely available and may be modified. In
practice this means that; phpList is very adaptable, easy to change
and improve. Open Source development relies on communities of
users contributing to the project they use. You pay nothing for the
software, but you are encouraged to collaborate with the project
though contributing code and/or though bug reports, translations,
documentation, spreading the word and if you feel it has enriched
your life, you can even donate!

WHAT IS PHPLIST.COM?

8

phpList.com offers phpList as a service is the cheapest way to have a
fully working installation without having to worry about servers,
blacklisting, bounces and deliverability. We manage the day to day
maintainance of the software including updates and security.
Using phpList.com is also a great way to support the future
development of phpList.

WHAT DOES PHPLIST NOT DO?
phpList is a one-to-many email program. It cannot easily be used to
have "email conversations" many-to-many as you might do on
software such as mailman

FEEDBACK
Discuss this chapter here.

9

2. CASE STUDIES
Below are six examples of how phpList is used, including a small
business, a large business, a city and a community group. They are
ordered by the number of emails sent per month.
Large Business - 500,000 to 6 million emails per month
Artist & Record label - 10,000 emails per month
Re-seller - facilitating several phpList installations
Small business - 500-1000 emails a month
Government department - 500 emails a month
Community Group - less than 100 emails a month

LARGE BUSINESS
BroadwayWorld.com is "the largest theatre website in the world" and
is devoted to all things Broadway and theatre. Their website has news
about shows, audition listings, user forums and a blog.

BroadwayWorld.com has around 500,000 subscribers on their phpList
system, and these are divided into smaller lists by State and/or
Country, for example.
They grow their lists by sign up's though their website and from
special offers and promotions throughout the year.

10

They send 2 to 3 campaigns per week which provide news and
information to theatre lovers. They have an average open rate of 38%.

The aim of the BroadwayWorld.com newsletter is to provide readers
with relevant information and special offers for Broadway shows and
related media on behalf of advertisers.
Their phpList system is managed by two staff members: one who
collects the information from the advertisers and assembles
campaigns and another who updates the lists and sends the
campaigns, as well as dealing with any technical issues. They
sometimes seek additional paid technical support from phpList Ltd.

11

BroadwayWorld started their newsletter in 2003 when they launched
their website: a newsletter has always been integral to their business
model. Initially they used proprietary hosted solutions which they
found too expensive. They then tried using a 'homegrown' solution
but they soon outgrew its capabilities. For them phpList was the
happy medium: easy to scale, free and within their technical
capabilities to host. BroadwayWord has been using phpList since
2009.

ARTIST & RECORD LABEL
Attila Fodor (FineCutBodies) is a musician, producer and a former
developer (of playstation games!).
He runs an indie record label which has had more than 60 releases
and hundreds of gigs since 2000. He goes on world tours and has
aired over 700 hours of radio content in the last 15 years. He also
teaches at the Budapest School of Music Technology, running a
regular class on digital technology and basic sound design paradigms.
He is a regular phpList contributor.
FineCutBodies community profile

12

FineCutBodies started a newsletter when he founded his record label
in 2001. He began by pasting email lists into the Bcc line in his mail
software. When the list started to grow he tried a few different
newsletter programs.
In 2014 he started searching for a newsletter software which could
provide bespoke functionality and smooth website integration. As an
audiovisual coder and video game developer, FineCutBodies has used
his coding experience to customise phpList to his needs.
fine cut bodies download for subscribe offer
One example of this customisation is his download-for-signup system,
where a visitor to the FineCutBodies.com website requests a free
track/tool download in exchange for signing up to the mailing list.
They then receive an email with the download url in: when the url is
clicked the visitor is subscribed to the list on his phpList system.
Additionally, subscribers are integrated seamlessly into the phpList
system using javascript, rather than using the standard phpList
subscribe pages.
fine cut bodies subscribe button on homepage
FineCutBodies has a total of 10k emails across several public lists, as
well as a private list for pre-release news aimed at music journalists.
The subscribers come from various online contact and sign up forms
(see screenshot as well as the subscribe-for-download deal).
FineCutBodies send one campaign per month per list and have an
average recorded open rate of 20-30%.

RE-SELLER
Marsha Perry is a website developer. She specializes in small business
websites, WordPress websites and WordPress coaching. Her company
also provides phpList installations, migration, updates and integration.
marsha perry website
Marsha also uses phpList for her own newsletter and it is her software
of choice for newsletters in most circumstances. As a developer she
finds it reliable: she said “some applications are ‘twitchy’ or delicate.
phpList is a workhorse.”
Her customers like phpList for a whole variety of reasons:
They can have multiple lists and sign up forms with one
installation.
They can migrate to phpList without making subscribers opt-in
again.
They love that the software is free to use and well-supported via
the forum
They appreciate the flexibility and control they get.

13

Marsha does not think many of her customers are really aware of
what Open Source means, but she feels they do appreciate some of
the consequences of phpList’s Open Source status, especially that
Marsha can tweak the code for them.
marsha perry newsletter signup phpList
Marsha also offers phpList Hosted, as it is the perfect solution for one
of her customers with a large mailing list. They had previously
considered moving that customer’s website to a host that allowed
more outgoing emails per hour. Then she realized that with the
Hosted version of phpList the website did not need to be moved.

SMALL BUSINESS
Ethical Pets is an online store
ethical pets gazette phplist
based in the UK which sells Bio/Organic, ecological and fairly traded
pet products.
They began using phpList Hosted to send out a newsletter called The
Ethical Pets Gazette five months after they launched their store, and
have now been running the list for nearly three years.
Ethical Pets
Publicise the ethical qualities of new products
Share blog articles about environmental and animal welfare
campaigns
Encourage the feeling of friendship and community present in
fairs and festivals
The Ethical Pets Gazette now has 750 subscribers. Most are
customers whose addresses were exported from online shop
software. There is an AJAX sign up form on their shop front and they
sometimes segment their lists to target specific customer groups, for
example, dog owners or cat owners.
Their average open rate is as high as 36%.>

GOVERNMENT DEPARTMENT
The Parliament of South Africa is legally required to inform the
citizens of South Africa about their work. Responsibility for this task
falls on the manager of the Content and Information Unit at
Parliamentary Communication Services, who is mandated to spread
this information to as broad a range of readers as possible.
One of the methods used is the Insession newsletter, which is
published on a monthly basis on their website as a pdf and e-book.

phpList is used to target the audience that wish to receive this
newsletter digitally. insession is sent to subscribers as an HTML email
with links to longer articles on the government website.

insession magazine email

14

The Content and Information Unit have used phpList since March
2013, and the software was chosen by the IT department.
Currently the Insession list has about 450 members, all of whom
subscribed themselves via a web form during the normal course of
parliamentary business.
in-session sign up form
Four staff of the Content and Information Unit manage the phpList
installation. Two have access to the subscribers' replies and two
upload the newsletters as an ebook and pdf onto the
parliament.gov.za website.
The government of South Africa also uses phpList to run an internal
parliamentary list.

COMMUNITY GROUP
The student group アナグマ・エイサー (Anaguma Eisa) at UW-Madison
teaches and preforms Eisa, a form of Japanese folk dance, originating
from the Ryukyu islands of southern Japan.
The group have been using phpList since 2014 to further their mission
to encourage people of all ages and abilities to develop their full
potential through cultural understanding and performing arts.
collecting emails for phpList on paper
Before adopting phpList they had been copy-and-pasting a small list
of addresses into Bcc for each email update. Now in their second year
of being an officially registered student organisation this method
become untenable.
They decided to set up a newsletter and list management system to:
Keep prospective and current members engaged with the latest
activities and concerts
Communicate better with those who do not regularly check
Facebook and Twitter
Communicate by email more often, because this channel is
more visible/high impact than social media
Tell people about events in a way that is easier to refer back to
(than social media)
Create a system which can be run by multiple group members
so they can share administrative responsibilities
Lucas Schneider, the president of Anaguma Eisa, chose phpList
because:
It is Open Source software
Liked the clean look of the interface
Felt it would be easy to manage several different lists
Wanted to be able to embargo and end campaigns relating to
performances (scheduling)
Wanted the flexibility to compose anytime but send at a regular
time (scheduling)
Wanted to edit the 'from line' with ease
Wanted to take advantage of the detailed statistics provided with
each campaign

15

a subscribe page, phpList
In the first few months of using phpList their list grew from 15 emails
to 35 emails, across 3 lists. The society run:
A list of active members of the organization
A list for announcing upcoming performances
A list for a general newsletter
collecting subscribers via twitter
The group add new members to their lists in three ways:
Manually adding addresses from paper lists from student
organization/freshers week fairs (photo 1)
New sign ups from the form integrated into their website (photo
2)
Sharing the subscription link on social media (photo 3)
They send 6 to 7 email campaigns each month: one email a week to
active members with information about rehearsals and
administration, one email a month to announce performances and a
more general newsletter every couple of months. Their emails have
an impressive average open rate of 50%.

FEEDBACK
Discuss this chapter here.

16

3. ABOUT THIS MANUAL
This manual has been written by the phpList community
documentation team, individual volunteers, companies and phpList
Ltd staff.

AIMS
This manual will tech you how to use phpList. It provides real life
examples where possible and chapters are goal oriented. We hope
you will come away from each chapter with inspiration and motivation
as well as an education!

TARGET AUDIENCE AND ASSUMPTIONS
The manual is aimed at users with average tech skills who are
starting at the beginning with phpList. The first sections of the book
assume that the reader has access to a pre-configured phpList install
to play with, perhaps on phpList.com or provided by their employer. If
this is not the case, then there are chapters about installing phpList
later in the book which can be used to get started.

DISCLAIMER
Software is not static, it continuously changes. phpList is no different
from other software, in that it is regularly updated to fix issues, add
new features and respond to a changing environment of browsers
and internet technology. This manual attempts to provide you with a
guide to how phpList works, but the version you are using may be
different from what is described here. The manual should help you to
work phpList in a general way, but you may need to interpret it for
your situation to make phpList do what you want it to do.

HOW TO USE THIS MANUAL
Most chapters will walk you through a task, with a screenshot for each
stage. It may be that you only require assistance with one aspect of a
task, in which case skip ahead.

STYLES
In this manual, words in Bold generally mirror the word in the
application itself. Additionally, each level of a menu is signified with a
>. If you need to go to Subscribers in the main menu, and then click
Add new in the sub menu, the we would annotate this as
Subscribers > Add new.

DOCUMENTATION TEAM
Thanks to all the the following contributors, in no particular order:

17

Dragonrider, Nikita Lyalin, Paul Mellors, Dan Waterloo, Elisa, Michiel,
Mariela, Orsiris de Jong, JoJo, Lucas Schneider, Guido Hornig, Vedran
Vucic, Sylvain, Andreas Tolfsen, Titano, Charlie Russell, Joseph Morris,
Björn Balazs, Mindhack, Alexandru Berendei, Marius, Sam Tuke,
Marcela Lopez Levy, kitchm, Rodrigo and Linda Ainsworth.

FEEDBACK
Each chapter in this manual has a corresponding discussion thread on
our forums, linked at the bottom of the chapter. For example:
Discuss this chapter here.
You can use these forum threads to discuss a chapter, for example, if
something on your system differs from the description in the chapter,
if an instruction in the chapter does not work for you or if have an
idea to improve a chapter generally. For more information see the
documenters home page.

18

BASIC USAGE
4.
5.
6.
7.
8.

LOGGING IN
ADDING YOUR FIRST SUBSCRIBERS
COMPOSING YOUR FIRST CAMPAIGN
SENDING YOUR FIRST CAMPAIGN
BASIC CAMPAIGN STATISTICS

19

4. LOGGING IN
The first thing you do to use phpList is log in. This chapter assumes
that you already have an installation and that you have a user name
and password.

PHPLIST WHEN YOU ARE LOGGED OUT
When you are not logged in, any page you visit in your phpList
installation will prompt you to enter your username and password. For
example, if I visit my dashboard, which usually resides at mydomain.com/lists/admin:

I would see my login prompt, marked below in red.

HOW TO LOG IN TO PHPLIST
To log in, enter the username in the Name: box and password in the
Password: box, then click Continue. The default username is
admin, however, your system administrator may give you a more
personalised login.

20

When you have successfully entered your username and password
you will see the page you were trying to access. In this case, the
Dashboard.

It is a good idea to bookmark your dashboard and use it as the
primary way to access your phpList. Depending on your configuration,
your dashboard might look a little different, for example there might
be more items on your menu bar.

HOW TO LOG OUT OF PHPLIST
The Logout button will always display in the top right of your
installation.
Remember to logout when you are not using phpList: your installation
contains the personal data of your subscribers and it is your
responsibility to keep it secure.

21

FEEDBACK
Discuss this chapter here.

22

5. ADDING YOUR FIRST
SUBSCRIBERS
This chapter will explain how to make a list of email recipients, called
subscribers, and how to send your email campaigns.
phpList is a powerful tool: there are several ways to add subscribers
and demographic information about them (name, location, interests
etc).
In this chapter we are going to cover the most basic scenario.

HOW TO GET YOUR FIRST SUBSCRIBERS
The chances are, if you are planning to use phpList, you have some
subscribers already. You may have a complex database of contact
information, a list you exported from an application, or a simple list of
emails on a sheet of paper.
In this example, we will be following the progress of Ethical Pets, who
we introduced in the Case Studies chapter. They will be emailing
customers of their online shop. The list of emails was obtained by
exporting a list of customer emails from their shop software.

CREATE A LIST IN PHPLIST
First of all you need to create a subscriber list. This will help you
organize your subscribers. In phpList, you must have at least one list,
but you can have many of them. In this example, we will create just
one list called The Ethical Pets Gazette, which is the name of the
Ethical Pets newsletter.
First, navigate to Subscribers > Subscriber lists in the main menu.

This will take you to a page which shows you all your lists. Currently
you can see just one list, a system default list called test.

23

To create a new list click the Add a list button.

You then need to enter your List name and List description (which
may be displayed publicly).
In this case, you tick the Public list box too, because we want people
to know about the list.

ADD SUBSCRIBERS TO PHPLIST BY COPY
AND PASTE
Once this page is complete, click Save. You can edit this page again
later if you need to. Next we click Add some subscribers

24

This will bring us to the Import Subscribers by Copy and Paste
page.
We now need to copy our list of subscribers. In this case, the list has
been stored in Libreoffice Calc. Right click the column which contains
the emails and click Copy.

Then, returning to phpList, we right click in the input box and select
Paste.

25

Finally, we click Import emails.

And we are informed of the results of our import,

26

CHECK IT OUT!
If we return to Subscribers > Subscriber lists in the main menu,
we can see the new list and its subscribers.

ASKING AND ASSUMING PERMISSION
Before you start to make lists, take some time to consider who you
add. A healthy email list is full of people who want to receive your
mail: they should have given you their email address voluntarily and
ideally been asked for permission before you add them to the system.
There are legal requirements in some countries which reflect the
importance of informed or assumed permission, for example, antispam laws in Canada.

LONG TERM SUBSCRIBER LIST HEALTH
27

The ideal situation is for your list members to join and leave your list
as they please. You can set up Subscribe pages so people can
subscribe themselves to your lists, and the (mandatory) Unsubscribe
link in your emails will allow people to leave if they want to. These are
discussed in detail in other chapters.
While you may be keen to spread your message as far and wide as
possible, always bear in mind that excessive, aggressive and intrusive
emails can tarnish your brand. Don't become a spammer!

FEEDBACK
Discuss this chapter here.

28

6. COMPOSING YOUR FIRST
CAMPAIGN
In this chapter we will talk through composing and sending a very
basic email campaign, which contains a simple piece of news and a
single image.
The example follows on from the previous chapter, using Ethical Pets.
In this scenario a "short dated" cat food needs to sell quickly. They
decide to email all their customers to tell them about the special
offer.

GETTING STARTED
To start a new campaign in phpList, navigate to Campaigns > Send
a campaign from the main menu.

This will open up a five-tab dialogue which will guide you through the
build-and-send process. Please note that various settings and plugins
add more tabs.
Message composition of the campaign is done in the first tab - the
Content tab.

The Content Tab
There are three tasks to complete in this tab. You must write your
subject, edit the From line and create your message in the
compose message window.

29

SUBJECT LINE
The subject of the email is the first thing that your subscribers will
see, so it's very important. Make sure that your subject line:

Is honest about the content of the email
Avoids spammy sounding words or phases (Free, hot,
opportunity, risk free, etc)
Is less than 50 characters long if possible
Is eye-catching and appealing
Is easy to understand, with a clear meaning or appealing hint
Contains a "call to action" if possible/appropriate (so Read, Buy,
Sign, Donate)

Sometimes you will have to compromise, prioritizing some of these
points above others.
Here is what Ethical Pets said about this subject line:

30

"The most urgent goal was to sell the food, so the subject needed to
be eye-catching. 50% off is pretty eye-catching, however, we know
that it could get flagged as spammy by filters, so the wording was a
little risky. We also needed be super clear that the food was short
dated.
To both things make this possible within the 50 characters we had to
shorten the super clear "Best Before Date: 20th of August" to the
more concise "(BB: 20/8/14). This would make sure that the best
before date would be visible in the subject line.
We also decided that the tactile and soothing "Puuuur" sound in the
little joke at the beginning was worth sacrificing a direct call to action
such as "Buy Organic Cat Food, 50% off", especially as using "buy"
and "50% off" in the same subject line would make it even more likely
that the mail would get flagged as spam."

THE FROM LINE
The second step is to edit the From line - your subscribers will also
see this information. In phpList this information is usually auto-filled
from settings in your system configuration, and is formatted Name
[space] email. In this case the automatic information was originally:
admin info@ethical-pets.co.uk.
Ethical Pets changed it to "Admin" to "The Ethical Pets Humans". They
said
"Admin seemed a little unfriendly for the purposes of this email, so we
changed the name to something more fun, and it really fitted into our
campaign. however, the email remains the same.We usually just write
Ethical Pets though. We always use our real email, because
sometimes we get replies from customers too, which is great."

Ethical Pets allowed replies to their email, however, you may wish to
use a "do-not-reply@example.com" style email: this depends on the
number of replies you tend to get, what they are about, and the
purpose of the email.
For detailed information about formatting the From line click in the i
information button next to it.

THE CONTENT
The next step is to compose your message. In this example, we will
compose the message directly in the phpList Content window.

31

Assuming you have your What-You-See-Is-What-You-Get (WYSIYWG)
composer plugin installed and enabled (usually FCKEditor) you will be
able to edit in a way that is similar to a Word-Processor or a blog site.
In the example below, we have composed our text, and are using the
Italic button to draw attention to some text.

ADDING AN IMAGE
The simplest way to add an image to your campaign is to embed one
from your website, or from an external source such as Wikimedia
Commons. To do this you need to find the URL of the image from
your site.
Depending on your browser, this may be done by right clicking on the
image and clicking Copy Image Location or similar (in Internet
Explorer it may be under right click Properties).

32

Then, in your phpList window click the Insert/Edit Image button in
the WYSIWYG toolbar.

You will then see the Image Properties dialogue.
Paste the image url into the URL box (highlighted in red below) by
using control-v or right click Paste. You should see the image in the
Preview box below. If there is an error, the most likely culprit is the
URL.

33

Image formatting and metadata
You should include an Alternative Text for the image. This will show
in place of the image when the image is suppressed by the recipients
email software, which is quite common. A good alternative text helps
encourage your reader to decide to view the images in the email: this
in turn makes your Campaign Statistics more accurate.
You may also wish to change the display size of the image: Ethical
Pets chose a Width of 200, and the height was adjusted
automatically because the Lock Ratio padlock is locked). You can
also chose to Align the image, in this case they chose Right, to make
it display on the right hand side of the email. They also gave it an
HSpace and VSpace of 5, which added 5px (just a little bit) of space
between the email text and the image.
Once you are done, click OK.

34

You will now see the image displayed in your email. If you wish to edit
it again, right click the image and click Image Properties.

CREATING A TEXT LINK
Now a link to the store was needed, to show subscribers where to buy
the food. To create a link, first highlight (with your cursor) the bit of
text that you want to become a link:

Next you click the Inset/Edit Link button

35

Finally, you paste the URL of the page you wish to link to into the URL
box, and press okay.

When your subscribers receive your mail they will see the link, as
below, and will be able to click the text to go directly to your website.
In your campaign statistics you will see how many clicks you had.

Once you have finished composing your message, you are ready to
move onto sending your campaign.

TEST YOUR CAMPAIGN
It is easy to skip this step because sending the mail is so exciting, but
it is really important to check... and after all, it only takes a few
minutes.

36

To send a test you need to enter your email into the Send text box
at the bottom of every screen in the campaign workflow. You can
send multiple test emails by separating the addresses with a comma it is a good idea to test in both Webmail (like googlemail) and a client
(like Thunderbird).
All the emails you send a test to must already be on one of your lists:
if they are not, you will be prompted to add them.
Once you have entered the email, click Send test.
Check that the
formatting is displaying as expected
your links go to the right places
you have not made any spelling errors.

If you find a mistake, edit your campaign and test again. Once happy
with your text part of your Campaign, click on the Next button.
phpList click next

FEEDBACK
Discuss this chapter here.

37

7. SENDING YOUR FIRST
CAMPAIGN
Once you have composed your html message, you are ready to move
though the tabs (highlighted in red below) which will guide you
through the process of sending your first mail.

FORMAT
If you have a template set up already then the Format gives you the
opportunity to choose it by selecting it from the Use template drop
down. Your html message will then be wrapped in the template during
the sending phase.
You can send a test message using the Send test box at the bottom
of the page, to see what your email will look like.
Click next when you have selected your template. If you do not yet
have a template, leave the -- select one in the dropdown and click
next.

38

SCHEDULE YOUR CAMPAIGN
After your tests you need to schedule your campaign should now be
on tab 3: Scheduling. Remember, some plugins and settings add
extra tabs so the tab number may change (but the name should stay
the same).
In this case we want to send the mail straight away, so the
Embargoed until time needs to be left as the default, which is
slightly in the past.
Additionally, because this campaign is not time sensitive, for example
there is no deadline for the special offer, we can leave the Stop
sending after time and date as the default too (far in the future).
When you have finished entering the scheduling information, click
next.

39

SELECT YOUR LISTS
One of the final stages in the campaign workflow is to choose the
list(s). In this case there is only one list to choose from, which is The
Ethical Pets Gazette. The options for All Lists and All Active
Lists are also useful; the former sends to every list, public or private,
and the latter sends to all public lists.
Remember that phpList will only send each subscriber one copy of
each campaign, even if they are on several lists: you don't need to
worry about sending people duplicate copies.

Once you have chosen your lists click Next

40

SENDING YOUR CAMPAIGN
Sending in phpList is a powerful tool with many possible
configurations. It is possible that your system administrator will give
you different instructions for sending or will send on your behalf.
The final tab in the sequence contains a few useful details and the
button which triggers sending.
First of all you can chose some emails that you wish to alert when
your campaign starts sending and finishes sending. This can help you
stay organized.
You can also choose to Reset click statistics - this means that any
clicks or opens recorded when you were testing your campaign will be
forgotten, so when you get new clicks and opens you know they are
from your subscribers.

When you are ready to send, click send campaign.

PROCESS YOUR QUEUE
41

Clicking send will add your campaign to your queue. There may be
only one campaign in the queue, or there may be several. Click
process queue to send the campaign now.

You will see the queue start to process, with a spinning phpList logo.

Next you will see something like the image below, depending on how
your system is configured.
Do not close your browser window until the process is complete,
unless your system administrator tells you otherwise.

42

ALL DONE?
When your queue has finished processing you should see the
following screen:

Depending on your configuration and list size, you may need to
refresh the screen and click resume processing a few times until the
process is complete.

FEEDBACK
Discuss this chapter here.

43

44

8. BASIC CAMPAIGN
STATISTICS
Now that you have sent your first campaign, it's time to take a look at
your campaign statistics. In this chapter we will look at Sent, Rate
Bounces, Forwards and Views, the four most fundamental
campaign statistics.

THE STATISTICS OVERVIEW PAGE
First, go to Statistics > Statistics overview.

This will show you a summary of all the campaigns you sent in the
past year (in this case, we have just sent one).

SENT
In this example, we sent our first campaign to 621 subscribers and
this is reflected in the SENT column. It is useful to see how many
subscribers you have for each campaign, so you can see your list
grow over the year.

BOUNCES
The second column BNCS shows the number of emails that
"bounced." A bounced email is one that cannot reach its intended
recipient. This could be caused by any number of things, for example:

45

The email is incorrect, does not exist or has an error such an
expired domain
The Mailbox is full (this may be temporarily or not)
A badly configured auto-responder (automated "I'm on Holiday
till" of "I got your message and will reply soon" type mails)
The exact definition of a bounce depends on your phpList
configuration, and it can take several days for a bounce to be
registered on the system. An email which continues to bounce will
eventually be either unconfirmed or added to a do-not-send list.
A high bounce rate may be a sign of poor list quality.
In this campaign there were 0 bounces.

FORWARDS
The third column FWDS shows the number of people who have
forwarded the mail through the phpList ForwardToFriend system.
This is dealt with in Advanced Statistics.

"VIEWS"
This is the most exciting of your statistics, but also the most
misleading.
In this case, our email was "viewed" by 156 of the 621 recipients,
which gives us an open RATE of 25.12%. However, it is important to
understand the limitations of this statistic, so you don't become
frustrated or disillusioned by what may seem like low readership
levels.
The VIEWS statistic:
Tells us how many people were recorded opening their email
(and presumably read the contents)
Tells us the minimum number of people who opened the email
And gives us a rate that reflects the number of people opening
an email compared to other emails we send.
Does not tell us exactly how many people opened the mail, or
what they did when they opened it.

An "open" is not always be recorded.
The major cause of inaccuracy when recording views is image
blocking. If images/remote content are blocked by a subscriber's
email software, then the action of your subscriber opening the email
cannot be reported back to phpList (or to any system). Image
blocking is therefore quite commonly used as a privacy feature by
email and webmail clients.

46

Only when your subscriber clicks, for example Show Remote
Content, is the view recorded in your campaign statistics.

Still a useful statistic...
This inaccuracy is the same for everyone, no matter which software
they are using to send their campaign; any "open rate" averages you
see discussed on-line or in books are subject to the same rules.
It is difficult to estimate how much higher your real readership is,
additionally the inaccuracy rate will vary from campaign to campaign.
If we bear this in mind, we can still make some comparisons, for
example "have I received more views over several campaigns" and
"how to I compare to the industry average"

What's the difference?
The difference between the real open rate and the statistic may be
very significant: in this case, a quick study found that only 1 in 3 of the
customers who bought the cat food in the hours after the email was
sent showed up in the open results, and the cat food offer was only
advertised by email. In this case, the real open rate could be more
like 80%.

Rate
To compare performance across several campaigns you can use the
RATE statistic, which is the number of opens expressed as a
percentage of the total sent. In this first campaign, we had an open
rate of 25%.

47

Over time, as our list keeps growing, we can still compare back to see
if we are keeping our subscribers interested. The rate statistic can
also be used to:
a/b test email titles and sending times
to compare readership between lists
and even to benchmark performance against industry averages.

SUMMARY
This Statistics Overview page is useful for comparing and
contrasting the success campaigns. This can help you to improve your
future campaigns. However, the statistics should not be taken too
literally.

FEEDBACK
You can discuss this chapter here.

48

GROWING AND
USING COMPLEX
LISTS
9. UNDERSTANDING SUBSCRIBERS AND
LISTS
10. CREATING YOUR LISTS
11. ADDING SUBSCRIBERS (TO LISTS)
12. CREATING A SUBSCRIBE PAGE
13. SETTING UP YOUR LIST CATEGORIES
14. USING ATTRIBUTES
15. USING PLACEHOLDERS
16. TARGETING YOUR CAMPAIGNS

49

9. UNDERSTANDING
SUBSCRIBERS AND LISTS
It is important to understand the nature of Subscribers and Lists in
phpList.

WHAT IS A SUBSCRIBER?
A subscriber is usually someone who is a member of one or more of
your lists. They may have subscribed themselves though a subscribe
page, or you may have imported their details from another source.
It is important to understand, however, that a subscriber may not be
on any list. This happens when you:
Import subscribers but do not assign them list membership
Delete all the lists a subscriber was a member of (without
deleting the subscriber)

WHAT IS A SUBSCRIBER PROFILE
All the data about a subscriber is stored in their subscriber profile.
This profile can be found by searching for their email in Subscribers
> Search Subscribers. To see all subscribers search for @.
Here are some examples of the kind of data held in a subscriber
profile:
On the Details page you can see information like ID, email address,
confirmed or not, blacklisted or not, number of bounces and html or
text emails. Some of this information is editable.

50

By clicking on the Lists tab you can see the lists which the subscriber
is a member of, and you can edit this too.

By clicking on the History button you can see all the campaigns that
have been sent to the subscriber.

By clicking on the numbers in the CLICKS column you can see
detailed information about which images and text links they clicked
on, when and how often.

51

As you can see, the subscriber profile is the central place where all
information about a subscriber is stored. This is very different to list
membership.

WHAT IS A LIST?
A list is a way of grouping together subscribers so you can send them
campaigns. However the list itself does not contain the subscriber
details. As you have seen, all that information is in the subscriber
profile.
You can view your lists by going to Subscribers > Subscriber lists
from the main menu. Next to each list is the number of MEMBERS
that list has.

However, if I delete the list, I have not deleted the subscribers.

Some examples of how this works in practice
A useful tool to help understand lists and subscribers is the All
subscribers feature, which was added in version 3.0.8. When this
feature is enabled (in the config.php file) you can see the total
number of subscribers shown alongside your lists.
Let's do some experiments with adding and deleting lists to see what
happens to the All Subscribers total.
At the start of our test, the number stands at 5327. That means we
have 5327 subscriber profiles in our system all together.

52

If we create a new list, and paste in the emails of some of our
subscribers, we can add these subscribers to the list and send
Campaigns to just a sub-section of our total number of subscribers.

The outcome is a new list (in this example with 662 members).
However, you can see that the All subscribers total stays at 5327.
This is because we have not added any new subscribers, we have just
created a list out of current subscribers.

53

Now, if we delete the new list with its 662 members,

the All subscribers count does not go down either, it is still 5327.

We can repeat this test, but this time add a mixture of current
subscribers (2) and new subscribers whose data we have never
introduced to phpList before (8). You can see phpList processes all
the lines, imports 8 new emails to the system and marks 2 as
duplicates.

54

All of these emails are added to our new list, and additionally, our All
subscribers count goes up by 8 subscribers to 5335.

We have added 8 new subscribers to the system, and phpList has
created 8 new subscriber profiles for us. If we delete our new list
again...

The List is deleted, however the subscriber count stays at 5335. We
have only deleted a list, we have not deleted any subscribers.

55

HOW TO DELETE SUBSCRIBERS
You should not delete subscribers in most circumstances. If a
subscriber wants to stop receiving emails from you they can
unsubscribe. Unsubscription means that:
Their email will be kept on the system and added to a do-notsend list (blacklist)
Your phpList system will never send a campaign to them again,
unless they re-subscribe
If you import their email again (by accident) you will not be able
to send them campaigns inadvertently
You have a record of when/why they unsubscribed which you
can use to improve your campaigns in the future
If you are in a situation where you want to delete some subscribers
rather than simply blacklist them, for example, to bring the size of
your lists down, first try the options on the Reconcile page, for
example to remove those with x number of bounces, those with an
invalid email and those who are not-confirmed.
The final resort is to get some emails by exporting them (from
Export subscribers) and then pasting whichever emails you wish to
delete into the bulk delete function. This can be found though the
Manage Subscriber page.

FEEDBACK
You can discuss this chapter here.

56

10. CREATING YOUR LISTS
In phpList you can organize your subscribers into lists. You must
have at least one list. You may find that having multiple lists, that is,
Segmenting your list, improves subscriber satisfaction and
opens/clicks.
There are several factors to be aware of:
You must select at least one list when sending
You can select several lists or use the all lists function when
sending
Subscribers will never get the same campaign twice, even if they
are on several of the lists you select
Lists can be categorized to help you keep organized
Lists are not the same as Attributes
Now that you know the basics, it's time to get started.

GO TO YOUR LISTS PAGE
Go to Subscribers > Subscriber lists from the main menu.

This will take you to your SUBSCRIBER LISTS page, where all of
your lists will be displayed.
There are two lists by default, test and newsletter.
You can view lists by category, or view lists which have no category
by selecting Uncategorized from the dropdown menu.

57

ADD A LIST
Click the Add a list button at the top of the page.

Fill out the details using the guide below to help you.

58

List Name
This will help you to keep your lists organized and remember what the
list is for. If your list is public this name will be displayed on your
subscribe pages. If your list is private, the name will be known only to
you (and possibly to other people who manage your phpList
installation).

Public List
The Public List box should be checked when
You want subscribers to be able to add themselves to the list
using a subscribe page
You want subscribers to be able to leave this individual list (but
stay on others)
You have chosen a list name and description which you are
happy to display publicly
If you do not make the list public, it is considered private, and it will
not be seen by your subscribers.

Category
Categories can be used to help organise your lists. If you decide to
use them there is lots of information in the categories chapter,
however, here is a summary:

59

If you have no categories then the category dropdown will not
display on this page
You must use categories if you have more than 16 lists
If you have some categories already but you want to leave this
list uncategorised then simply leave -- Choose category in the
dropdown
In this instance we had already set up some categories and chose the
category Gardening from the dropdown.

List Description
This information will display on your subscribe pages if the list is
public.
Save and repeat
When you have filled out the page click Save. You can come back
and edit the info again later if you need to. You can create as many
lists as you need.
You will be prompted to add some subscribers to the list. See the next
chapters for more guidance.

FEEDBACK
You can discuss this chapter here.

60

11. ADDING SUBSCRIBERS
(TO LISTS)
There are three main ways to add subscribers to your phpList
installation:
copy and paste a list of emails
upload a file with emails
upload a CSV file with emails and additional data.

This chapter deals with each of these methods in three stages
When and why you might use the import method
Preparing your data
Importing your data

WHY IS (TO LISTS) IN BRACKETS?
It is important to remember that:
Subscribers can exist on the system without being a member of
any list
In this chapter is assumed that you will be adding subscribers in
the form of a list, but you can add them without
making/choosing a list if you want to
When you add a subscriber to the system for the first time, a
subscriber profile is created
Adding the subscriber to more lists does not create more
profiles, all the subscriber details are saved in one profile no
matter how many lists the subscriber is on
Deleting the list does not delete the subscribers.

61

You can read the chapter about the difference between subscribers
and lists for more information.

COPY AND PASTING
Why and when to use this method
If your data is very simple, just a long list of emails in a paper or
digital document, then this could be the method for you - especially if
you are not very confident with file formats.
If the emails are on paper then you could type them directly into the
import dialogue, however, it is probably better to type them into a
document first.
This is also the method you will use when you create a new list from
subscribers that are already on your system.

Preparing your data for this method
Preparation for copy and pasting the emails in is minimal. You may
need to do nothing at all.
If your emails are in a text file or a word-processing file, you need to
open the file with the emails in, and make sure the data is just a list of
emails, one on each line and with no punctuation.
If your emails are in a spreadsheet or csv file you do not need to
prepare them. However, if this is the first time you will be adding the
subscribers to the system you may wish to use a csv import to allow
you to add more of your data to their subscriber profiles.

Importing your data
If your data set consists of a list of emails in a file, like this:

62

Or a complex data set in a spreadsheet like this, from which you only
wish to upload the emails

Then first you need to select them in your document and copy them.
This is often done by pressing:
Control+C or
Right click > Copy or
Edit > Copy.
Then go to Subscribers > Import emails from the main menu

63

Click the copy and paste list of emails button in phpList

You will then see the following page:

64

First choose a list by ticking the box next to the list name.
You may also Add a list, or tick All Lists. Also, it is best to leave
the Check to skip emails that are not valid box ticked. Next,
paste your emails into the box, using
control+v
Or right click and Paste.

65

Click the Import emails button.
You will then see the results of your import.

UPLOAD A FILE WITH EMAILS
Why and when to use this method
If you have a digital list of emails with no other data, and you know
how to save them as a text file, then this is the right method for you.
If you have more than just emails in the file and you want to upload
all of the information, you will need to use the CSV import.

Preparing your data

66

Your file needs to be formatted:
One email per line
No spaces, tabs, commas etc.
You need to save it as plain text (filename.txt)
You should only edit it in a text editor such as NotePad, TextEdit
or Geany.

It is still possible to import this data when there is additional
information after the email, for example:
FinelyMay@einrot.com age 23 from Southport likes chips with curry
sauce
But, everything after the end of the email will be discarded.
Additionally, if you have any punctuation attached to the end of the
email, for example,
FinelyMay@einrot.com, age 23 from Southport likes chips with curry
sauce
then the data will be corrupted because the comma at the end of the
email address will be imported as part of the email.

Importing your data
Go to Subscribers > Import emails from the main menu

67

Click Import by uploading a file with emails.

You will then see the Import Subscribers From Text File page.

68

First choose a list by ticking the box next to the list name. You may
also Add a list, or tick All Lists. Then select a file to upload by
clicking the Browse... button. Navigate to the file on your computer
and click Open. Then click the Import button.

69

You will see the emails importing.

Upload a CSV file: emails and some additional information

Why and when to use this method
This is the method used when you have a spreadsheet full of data,
where there might be names, emails, addresses... Often this data will
have been exported from another source, such as a CMS, CRM,
webshop, database or email address book.
If you have such data, it is a good idea to upload a CSV file the first
time you add subscribers to the system and you are asked to make a
list (even though you will only be prompted to copy and paste). From
then on, unless you need to re-synchronise or add some new data,
you can just use copy and paste to add subscribers to lists.

Preparing your data
When you have emails and some additional information, such as
Name and Gender, you need to
Open the data in a spreadsheet
Rename some columns to avoid or utilise phpList system values
Save as a csv - make a note of the delimiter.
Example Dataset for CSV Import
In this example we have ID, title, first name, email address, height in
cm and gender, and they are stored in a spreadsheet format (xls, ods
or similar).

70

Data that includes an ID
When you use another application, a blog, webstore, CRM software
etc, you may want to keep the data in phpList synchronized with the
data in your other app.
phpList allows you to do this accurately by using a foreign key: this
means that the ID tag or number used to identify an individual in your
other application can also be used to identify a the subscriber in
phpList. This means that:
If a subscriber's email address changes in your other app, this
can be updated in phpList
Any changes to subscriber attributes can be updated
automatically, for example surname, location, date of last
purchase form your store.
If you wish to use the ID as a foreign key you should rename the
column ID (or similar) to foreign key.
Renaming columns to avoid phpList system values
Some words are already used by phpList to describe data: these are
called phpList system values. phpList will not allow you to import
data from columns in your CSV when certain system values are used
as a column title. These columns will simply be skipped when you try
to import.
It is common for other software and web applications to use the same
system values. Columns must be renamed before the data exported
from one app can be imported into phpList. Here are some examples
(a full list can be found later in the chapter):
ID
confirmed
passwordchanged
Renaming columns to match phpList system values
Some columns can be renamed to match phpList system values,
because those system values are designed to take imported data.

71

In the example below we rename the column Email address to
Email. It is possible to achieve the same thing during import by
mapping one term to another.

As another example, the ID column can be renamed to Foreign Key.
This allows the data to be put to use in phpList when otherwise it
would just be skipped. In this case, phpList would not allow you to
map ID to Foreign key during import so this task must be done before
upload.

A list of system values
Here is a table containing a list of all the system values and how
phpList will deal with columns with that name if you try and import
them.
List of system values and how phpList will respond if they are column
names.
id

Will be skipped

email

Will import

confirmed

Will be skipped

blacklisted

Will be skipped

optedin

Will import

bouncecount

Will be skipped

entered

Will be skipped

72

modified

Will be skipped

uniqid

Will be skipped

htmlemail

Will import

subscribepage

Will be skipped

rssfrequency

Will be skipped

password

Will import

passwordchanged

Will be skipped

disabled

Will import

extradata

Will import (as attribute)

foreignkey

Will import

unique_1 (2, 3 etc) or index_1 (2, 3 etc)

Will be skipped

Saving the file
Next we need to save the file as a CSV file, a comma separated value
file. You should ideally change the delimiter to tab. If it is not tab, you
will at least need to be aware of what the delimiter is so you can tell
phpList when you import.

IMPORTING THE SUBSCRIBERS
First go to Subscribers > Import emails from the main menu.

Click the final option for import by uploading a CSV file with
emails and additional data.

73

You will then see the Import Subscribers From CSV Page.

First choose a list by ticking the box next to it. You may also choose
All Lists or Add a list.

Next upload your CSV file by clicking Browse..., choosing the file on
your pc and clicking Save.

74

You must also indicate the delimiter, this is what separates each item
in your CSV (in place of the column lines). If you are unsure what the
delimiter of your file is, you can open the file into a plain text editor
such as Notepad. You will see what is separating the items. In this
case it is a comma, so we put a , in the Field Delimiter box.

There are various other options on this page, which all have a
description. Generally, it is good to keep the Test Output option
checked.
Use the Overwrite existing and/or Retain old email options to
preserve the data set which should be held safe; it is the source of
most up-to-date data.
When you have finished filling out this form, click Import.

You will now see a page where you can match the data in your file to
attributes on the system. Attributes such as Foreign Key and Email
will not appear on this page because the system deals with them
automatically: all the attribute on this page are new to the system.

75

Click on each dropdown - is the correct attribute already in the list? If
not, select Create new one. This will create a new attribute in your
phpList so that next time you import similar data the system can deal
with it automatically.

Problem? If you see something like the image below, where all your
attributes are on one line, then you have used the wrong delimiter.

You will also see some test data, that will give you a strong indication
of whether your import is going well. Each column title from your csv
should line up with some data about one of your new subscribers.

76

Problems?
If you see anything wrong in the test, do not proceed! Click the Reset
import session button to start again, check your delimiter settings
and/or get help. A messy import is no fun to fix!
When all attributes have been dealt with and you are happy with your
test data, click Continue.

You will be shown a summary of what will happen when you import.
Now you can see that Foreign Key and Email are matched
automatically, and all your other attributes will be created for you.

77

If you are satisfied, click Confirm Import.

You will see that your subscribers and their data has been imported.

FEEDBACK
You can discuss this chapter here.

78

12. CREATING A SUBSCRIBE
PAGE
A subscribe page usually consists of a short form that a visitor to your
website can fill out to subscribe themselves to one or more of your
lists. Here is an example:

In the example above, the subscriber is asked to input their email
address and to confirm it. They can then choose to receive a text
version format and they can add their first and last names if they
wish.
In phpList you can have an unlimited number of pages, combining any
set of Attributes, Lists and Languages.
Additionally you can use pages in conjunction with scripts to create
subscribe forms which integrate more closely with your website. As
this is a custom-made process for individual sites we do not have
generic documentation about it.

CREATE A PAGE
To get started with your subscribe page visit Config > Subscribe
Pages.

79

Initially you'll find this page empty, with no subscribe pages to display,
although there is a default subscribe page at
www.yourdomain.com/lists.
The first page you make will replace this default page and later you
can set any page as default.
To create a new page click Add a new subscribe page.

This will open a page called EDIT A SUBSCRIBE PAGE.

CUSTOMIZE A SUBSCRIBE PAGE
The subscribe page editor is broken into four collapsible areas:
General information
Transaction messages
Select the attributes to use
Select the lists to offer

80

These sections will guide you though creating a subscribe page which
meets your specific needs.

GENERAL INFORMATION
The first box edits the titles and text on the page. Enter your title in
the Title box first of all.
You can leave Language file to use as --default, unless you are
creating a page for a language other than the one you use for your
installation, for example, if you are creating a multi-lingual system.

You can change the text in the intro too.

81

The Header and Footer dialogues are used for html editing, and the
default code in them is taken from Config > Settings >
subscription-ui settings. We will discuss this further in the
Subscribe page design and configuration chapter.
You can edit the text in the Thank you page and Text for button
too, however, the standard texts are suitable for most situations so
you may wish to just leave the defaults as they are.

GENERAL INFORMATION: HTML OR TEXT
The last section of the general information sections is on HTML
Email choice. It is very important and it directly affects the quality of
your lists and the subscribe satisfaction.
You can create a HTML email in phpList, with images and other design
elements, and also a plain text version, with just text, no images,
colours etc. Some subscribers prefer only text, they may want plain
text for technical reasons, for example for compatibility with assistive
software for a visual impairment, or it may simply be a personal
preference.
If you are planning on sending HTML messages you will want to avoid
large numbers of your subscribers accidentally signing up for text
only emails. You will have wasted time on a design they will never see
and they may be less interested in your mails.
It is therefore worth spending time on this section, deciding how you
would like to present the text vs. HTML options.
The default (as of version 3.0.11) is Offer checkbox for text, where
the box defaults to unchecked on the subscribe page. This means
your subscribers will have to manually choose to receive text emails,
but the option is there for those who need/want it.

82

If you intend to send emails in HTML format it is best to make the
"path of least resistance" be the signup for HTML. Many subscribers
will ignore the box, or may not know what HTML vs. text means.

TRANSACTION MESSAGES
These are the messages sent to the Subscriber based on various
actions, such as subscribe and unsubscribe. The defaults are taken
from Config > Settings > transactional settings. It is possible to
edit these, although the defaults are suitable for most situations.

SELECT THE ATTRIBUTES TO USE
This section allows you to choose which attributes, which
personal/demographic data, you will ask for from your subscribers on
the page.
You might ask for generic information like name and city, or
something more specific, like shoe size or hobbies. The use of
attributes is described in the Attributes and Placeholders chapters.
In this example we collected First Name and Last Name only and
we did not make either of them required because many people do
not wish to give out personal information. We had several other
attributes to choose from.

The Type: is defined in the attributes editor. The Default value can
be different on each subscribe page if needed.
Please note that if a customer does not change the Default
value when they subscribe, whatever you set it as here will be added
to your database.

83

SELECT THE LISTS TO OFFER
This final section allows you to select which lists to offer.
If you select only one list, then the subscriber will not be given a
choice. If you select multiple lists, then the subscriber will be able to
select which lists they want to join. In this example we chose only one
list.

SAVE YOUR NEW PAGE
Click the Save button at the end of the page when you are ready. You
will be able to edit the page again later if you want to make a change.
You will then be directed back to your Subscribe Pages list. We can
now see one page.

VIEW YOUR PAGE
To view your new subscribe page page click the magnifying glass icon
next to it on your subscribe pages list (Config > Subscribe pages
from the main menu).

84

Your page will look something like this:

USE YOUR PAGE TO ADD A SUBSCRIBER
AS AN ADMIN
One additional functionality of the subscribe page view is to add a
subscriber to your database quickly, without needing to go into the
administrative interface. If you view the subscribe page while logged
in as an adminiatartor, you will see an additional box:

85

This box allows you to add a subscriber by filling out the form on their
behalf, and you can specify if you need to send them a confirmation
request or not. This can be useful if you are talking to the new
subscriber on the phone, for example.

FEEDBACK
Discuss this chapter here.

86

13. SETTING UP YOUR LIST
CATEGORIES
When you have more than a handful of lists you will need to organize
them into categories. You will be promoted to do this once you create
more than 16 lists.
You can create categories to help you organize your lists at any time,
and so the exact method you should use depends on your situation. In
this chapter there are two suggested workflows.
1. Categories are set up before any lists are made (categories
before lists).
2. Categories are set up to help organize pre-exisitng lists (lists
before categories).
You should follow the section most appropriate to your situation.

CATEGORIES BEFORE LISTS
To create your categories go to Config > Settings

Scroll down until you find Segmentation settings

Enter the names of your categories, separated by a comma.

87

In the image above you can see I have made a list category called
veganism, for example. This is because I know I will have several
lists about veganism in the future, for example, recipes, campaigning,
events and philosophy.
NEXT, See the section about Using categories at the bottom of the
page.

LISTS BEFORE CATEGORIES
If you use phpList a lot and you are using list segmentation you will
soon end up with more lists than you can easily manage without
categorising. To start categorising your lists go
to Subscribers > Subscriber lists.

Then click Categorise lists.

88

If you have no categories at all yet, you will see the following screen:

Click Configure categories.
If you already have a few categories you will see a similar screen with
the Configure categories button (which you still must click) in the
top right.

Create your categories
Add your categories, one by one, with commas between them.

Click Save Changes.

89

Add lists to categories
Go back to Subscribers > Subscriber lists. Click the Categorise
lists button.

Select the correct category from the drop-down beside each list.
If a list is already categorized, it will not be displayed.

Carry on till all the lists are matched with a category if possible.

90

If you find a list that does not fit into a category you can keep it in
Uncategorized by leaving --Choose category in the dropdown and
make a new category later.
When you have finished click Save. Then, if you want to create more
categories click the Configure categories button at the top of the
page again and repeat the cycle.
If a list has already been categorised and you want to change the
category, you can do this by editing the list from the main lists page.

USING YOUR CATEGORIES
Once you have finished setting up categories, they should become
part of your everyday workflow with phpList.
For example, when you make a new list, you can assign it to a
category during the creation stage. In this image I have created a list
called Vegan Recipes and I can categorize it under veganism.

Also, as a second example of categories in use; when you send a
campaign you can look for your lists by using categories too.

91

FEEDBACK
Discuss this chapter here.

92

14. USING ATTRIBUTES
phpList is pre-configured to deal with some data about your
subscribers, for example email address, number of bounces
(bouncecount) and their phpList ID number: these are called system
values. Attributes are used for any other data you want to add to
the system about your subscribers, usually demographic information.
Some common attributes are Name, Age, Gender and City. Some
bespoke examples could be height, annual income, names of pets or
kids and favourite genre of book. The attributes you use are entirely
up to you to decide.
Once you have collected/uploaded attribute data, it can be used to
connect to your subscribers more directly and with better precision,
by using placeholders and the segment plugin.
There are two ways to create attributes:
Create them in bulk when you import a csv file
Create them manually from the configure attributes page
Edit them from the configure attributes page
This chapter will explain how to create attributes. How to use them is
covered by the placeholders chapter and the segment plugin
documentation.

CREATING ATTRIBUTES WHEN IMPORTING
DATA
When you import complex data using the "csv with additional data"
method, attributes can be easily created (in bulk) from column titles
which are not already listed as an attribute.
Do not create new attributes for email and other system attributes,
you must map those to the pre-existing system attributes listed in the
dropdown.
In the image below, five new attributes are being created, and
EmailAddress is mapped to Email.
Surname and Gender are standard attributes, however, the
subscribers' height in Centimetres is more unusual. phpList treats all
these attributes in the same way: there are no restrictions on the
subject matter of an attribute.

93

Once an attribute has been created, any column headed with the
attribute name in future csv files you import will be mapped to the
attribute automatically. You will not need to create the attribute
again.

If there is new data for a pre-existing subscriber, it will be integrated
into the subscriber details by using email address or Foreign Key as a
reference.
In the image below, for example, we have subscribers on the system
already, and now have added ShoeSize as a new attribute. Where our
new dataset provides a shoe size for a pre-existing subscriber, this
new attribute data is simply added to the details.

94

CREATING AND EDITING ATTRIBUTES ON
THE CONFIGURE ATTRIBUTES PAGE
To create or edit an attribute manually, go to Config > Configure
attributes from the main menu.

From there you can create a new attribute:

95

You can also edit existing attributes:

You can,

96

Specify/change the name
Choose/change the Type, which dictates the input method on
your subscribe pages (see the example edit below)
Choose/change the Default Value, which dictates the standard
value on the subscribe page (you may need to change this on
the Subscribe page editor too)
Make the attribute required, so subscribers must give the
information in order to sign up (warning: mandatory fields may
deter subscribers)
Additionally you may,
tag them to delete one or more attributes
tag to merge several attributes together

Example edit 1: changing the type from textline to
select
In this example we will change the Type of the attribute for
ShoeSize, which was automatically created during a csv file import,
from textline to select. First we change the type to select using the
dropdown menu, then we click the Save changes button at the
bottom of the page.

Then we click the edit values button which appears below the Type:
dropdown.

We can then add all the shoe sizes we want.

97

If you are editing an attribute that already has data in the system,
some values may already be listed: if you try to add these again
phpList will skip them rather than create a duplicate, so you can
simply list all the values you want rather than search through.

You can change the order of the values for the attribute. This will
affect the order in which they are listed in the dropdown on the
subscribe page. In this example the shoe sizes had become jumbled
because some were already in the system and some were not, so we
re-ordered them.

By changing the order, the choice given to subscribers when they sign
up is clearer.

98

USING ATTRIBUTES
The primary use of attributes is as placeholders. Please see the
placeholders chapter for information on how to use them. The
segment plugin and the attribute select plugin allow you to send
emails to subscribers with certain attribute values.

FEEDBACK
Discuss this chapter here.

99

15. USING PLACEHOLDERS
A place holder is a word in square brackets, for example,
[FIRSTNAME]
or
[UNSUBSCRIBE]
which will be replaced with real data, such as the subscriber's name
or a unique URL during sending.

PLACEHOLDERS IN PHPLIST
There are three types of placeholder in phpList:
System e.g. [UNSUBSCRIBE]
Config e.g. [WEBSITE]
Attribute e.g. [FIRSTNAME]
In this chapter we will deal with the Attribute placeholders only. We
will deal with system and config placeholders in the templating and
configuration chapters respectively.

WHERE TO FIND A LIST OF ATTRIBUTE
PLACEHOLDERS
When composing a campaign, you can find a list of placeholders by
clicking on the information symbol, i, next to the text Compose
Message.

Any Attribute placeholders will be listed here along with instructions
on how to use them.

100

These are generated directly from your chosen Attributes so if you
wish to edit them, please see the Attributes chapter.

HOW TO USE A PLACEHOLDER IN A MAIL
To use a placeholder, you need to type it exactly as suggested in the
information, i, box. This will include:
an open square bracket
the placeholder name (in Capitals, with spaces)
and a close square bracket
It is also wise to use some fallback words, that is words that will be
inserted in place of the data when the data is missing. You can
indicate the fallback words with the double percent sign %%.
Anything before the %% is the attribute placeholder. Everything after
the %% is the fallback text. The fallback text is optional.
In this example, the placeholder would either print the subscribers'
first name, and where the name is not known, it will print the word
Friends.

101

It is important that you test your placeholder before you send your
mail, as mistakes are ugly and disconcerting for your subscribers.

Set up two test accounts
To test your placeholder effectively you will need:
one subscriber profile suitable for testing the attribute
placeholder. You can use an alternative email to which you have
access, where the attribute data is completed
another subscriber using an email you have access to, where the
attribute data is not completed.
You may need to add these emails or edit your existing data to
achieve this. You can do all these things from the Search > Search
Subscribers page.
In the example below I have subscribed myself to the system using
my personal email (rather than my work email) and I have filled out
my name.

And I have another one using my old email address where the
attribute data has not been provided.

Send a test message

Next, enter the two test emails into the Send Test box at the bottom
of your campaign Content page and press Send Test. You may
need to confirm the emails if it is the first time you have used them.

Check the results
For the subscriber where the attribute related to the placeholder has
data, you should see that data in the email. In this example you can
see the name Anna is visible in the place of [FIRST NAME]

102

Where the subscriber has no data for the attribute, you should see
the Fallback Text. In this example that is the word Friends.

You can now send your campaign as usual.

FEEDBACK
Discuss this chapter here.

103

16. TARGETING YOUR
CAMPAIGNS
In this example, Ethical Pets are sending out a campaign about a
special offer on dog treats. They are targeting the campaign by only
sending it to customers who have previously bought products for a
dog.
There are several reasons for doing this:
It enables more campaigns to be sent overall, which increases
the impact of email marketing
Most people will receive fewer campaigns, so they are not
inundated
Campaigns will be more relevant to readers
Campaigns are quicker and easier to write, because they only
need to be interesting to the target audience and not to
everyone
It is easier to measure the impact of the campaign
In this campaign only 35% of the total number of subscribers were
emailed. Without segmentation either a large number of people
would have received a campaign with little relevance to them or
Ethical Pets would have needed to spend time tying to make the
campaign have a broader appeal.
The overall consequences of segmentation should be:
Happier customers
Fewer unsubscribes
More motivated marketeers
Improved sales/responses to calls to action
Improved customer loyalty/retention over time

SEGMENTING YOUR LIST
The method of segmentation depends on,
The quality of your data
Where and how your data is stored
What tools you have to segment it
In this example the segmentation was achieved using a Prestashop
plugin, which allows the exporting of customer details based on the
category of product bought.

104

Unfortunately the Prestashop core does not provide very detailed
data exports, and so a paid plugin was needed.
In other situations it may be possible to segment a list using:
spreadsheet software
database software
the phpList segment plugin, to split the list using attributes

ADDING A SEGMENTED LIST TO PHPLIST
A suggested methodology for adding a segmented list to phpList is:
Synchronise your data - upload any new subscribers to phpList
Create a new list
Copy and paste the segmented emails into the new list
phpList will pull in the rest of the data/attributes for you from the
subscriber profiles
Having synchronised the data by uploading the latest data using a csv
import, Ethical Pets went on to create a new list.
In this case a new list Dog category purchasers was created (note:
a private list, not public)

105

Then the emails from the prestashop segmentation export were
pasted in:

The segmented list of subscribers are now all members of the list.

106

SENDING TO A SEGMENTED LIST
The process for sending to segmented lists is the same as sending to
large, unsegmented lists. You simply select the list on the Lists tab of
the campaign workflow. In this example we have put the segmented
list in a category too.

EXCLUDING A LIST
If you are sending a lot of mails and there is a chance that
subscribers are in multiple segments and receiving lots of campaigns,
you could consider using the exclude list functionality.

107

For example, if Ethical Pets wants to send a campaign to a list of cat
product purchasers just a few days after they sent the email to dog
product purchasers, they could exclude anyone on the dog list from
receiving the cat related campaign.
While this involves prioritising which campaign is most important, the
dog or the cat one, it means that the people who buy both dog and
cat products are not receiving too many campaigns in total.

Activate the list exclude feature
You need to use
define("USE_LIST_EXCLUDE",1);
in your config.php

The line of code and comments can be found in the extended config
and copied over. If you do not know how to do this, you can find more
information in the manual installation chapter.

Using the list exclude feature
In this example, Ethical Pets have sent an email to the cat product
purchasers segment but excluded the dog purchasers segment.
During sending phpList checks if the subscriber on the cat list is also
on the dog list, and if they are, the email is not sent to them.

108

Additional ways to segment a list
Here are a few ideas for ways you could segment your lists:
Subscriber location
Subscriber interests
Subscriber demographic (gender, age, shoe size etc)
Subscriber actions (purchase, abandoned cart, signed petition,
recent comment etc)
Subscriber status (new to list, long-time member)
Subscriber preference: ask your subscribers how often or when
they would like to receive emails from you using an attribute on
your subscribe page.

ADDITIONAL BENEFITS OF
SEGMENTATION
There are many benefits to list segmentation:

109

You can a/b test aspects of your email, for example the
tone/style/grammar of the subject line
You can automate transactional messages, for example,
messages offering help to customers who abandoned a cart. You
can use a recurring campaign for this.
You can tailor very specific emails, for example about events, to
those who live in the location of those events.

FEEDBACK
Discuss this chapter here.

110

DESIGNING AND
ASSESSING YOUR
CAMPAIGNS
17. TEMPLATES
18. THE FOOTER
19. CREATING A TEMPLATE
20. MORE TEMPLATE PLACEHOLDERS
21. DIY: SUPER SIMPLE TEMPLATE
22. SUBSCRIBE PAGE DESIGN AND
CONFIGURATION
23. ADVANCED CAMPAIGN STATISTICS

111

17. TEMPLATES
The templating system in phpList is designed to create a workflow
that keeps things simple for the campaign creator.

THE TEMPLATING WORKFLOW IN PHPLIST
There are two elements to the workflow:
1. Creating and uploading a template; this is done very rarely
2. Choosing and using the template; this is done for every
campaign
Step one is the more complex and it is often done by a web designer
or system administrator. We cover this in the creating a template
chapter. There is also a really easy templates chapter to help you if
you do not have a designer.
The second part of the workflow is very simple. The person creating
the campaign simply selects the template by name from a drop down
menu after the campaign message has been written.
The template is then applied during sending, like a wrapper around
the text, and the person sending the campaign does not come into
contact with the template code at all.
The template is not applied to emails sent to subscribers who request
a plain text email.

AN INFOGRAPHIC ABOUT TEMPLATING IN
PHPLIST

112

113

FEEDBACK
Discuss this chapter here.

114

18. THE FOOTER
The phpList footer
Is an active feature of the software, not simply a description of a
design element
Can be edited for each campaign from the content tab of the
campaign workflow
Is replaced by a secondary footer when the Forward to a Friend
system is used
Should contain the [UNSUBSCRIBE] placeholder
Is placed in the template with the [FOOTER] placeholder

WHAT IS THE FOOTER?
In your template design you may have many elements which you
think of as being "the footer." In the image below, for example, the
blue and black coloured areas and all the content within them would
commonly be described as the "footer."
However, you may not wish to add all of this into your phpList footer.
For example, in the image below only the "update your preferences"
and "unsubscribe" elements are within the phpList footer system. The
rest is in the template itself.

You may wish to choose which items go into the phpList footer
carefully because:
The footer can be edited from the campaign composition tab:
you may or may not want certain items to be edited on a
campaign-by-campaign basis
If the forward to friend placeholder is used, all content in the
phpList footer will be replaced when the message is forwarded.

ADDING YOUR FOOTER
Everything that goes in the phpList footer is added separately from
the rest of the template.
To situate the a footer to your template use the [FOOTER]
placeholder.
the [footer] placeholder

115

You should design your footer as a separate .html file
creating a footer for phpList
To add your footer to phpList go
to Config > Settings and campaign settings
adding a default footer to phpList
Find Default footer for sending a campaign then click the edit
icon
edit default footer phpList
Paste in your footer code and click Save changes.
save changes to default footer
Your footer will now appear in the footer section of the content tab in
your campaign workflow, where you can tweak it.
footer in compose window
As well as in your campaigns when you send them
footer in campaign

THE FORWARD TO FRIEND FOOTER
On the Config > Settings page, there is a second footer called
Footer used when a message has been forwarded.
If you use the [FORWARD] placeholder, and a subscriber forwards
the email, this footer will replace the usual one. It contains the
following text:
This message has been forwarded to you by
[FORWARDEDBY].
You have not been automatically subscribed to this
newsletter.
If you think this newsletter may interest you, you can
[SUBSCRIBEURL] and you will receive our next newsletter
directly to your inbox.
If you wish to use the forward to friend system you should edit this
footer so that it has the correct appearance while maintaining the
appropriate text.

FEEDBACK
Discuss this chapter here.

116

19. CREATING A TEMPLATE
CREATING YOUR TEMPLATE
There are lots of ways to create your template. You could
Design and write your own
Pay someone to do this for you
Modify a generic/Open Source template that you have bought or
"recycled"
Use the super-simple DIY template in the next chapter.
Here are some tips to help you set up your template for use with
phpList.
If you don't understand the information in this chapter and you don't
have anyone to help you with your template, then skip to the next
chapter for a super simple template.

The Basics
You should use inline styles, and unless you have configured phpList
especially with a plugin, you must use a single column template.
If you choose a responsive template, your campaign editor should not
use images with a width larger than a smartphone screen (max 320
by 480 pixels).
The footer in phpList is quite specialized and is described in a
separate chapter. If you plan to have a footer in your design, please
read the footer chapter before you start work.

Logo: upload or remote link?
When you are designing or modifying your template, you need to
decide if you will include your logo in the campaigns as an attachment
or use a remote image. If you include your logo as an attachment it
will always display to the recipient.
an uploaded logo is included in your campaign
If you use a remote link, however, the image will only display when
the subscriber gives permission (in most email and webmail clients).

If you decide you upload your image then leave the local link (or just a
use a "broken link") and you will be prompted to upload the image
when you are adding your template to phpList.

A mandatory placeholder in the body
You must include some strings that phpList will replace during the
sending stage.

[CONTENT]

117

The obligatory string is [CONTENT]. This will be replaced with the
content of your message when you send your campaign.
the content placeholder in phpList [content]

ADDING YOUR TEMPLATE TO PHPLIST
To add a template to phpList, go to Campaigns > Manage
campaign templates from the main menu.
manage campaign templates phpList
You will then see a list of templates already in the system. By default
there is one template, the system template (which styles things like
the confirm subscription emails).
add a new template
Click Add new template.

NAME YOUR TEMPLATE
First, give your template a Title. This will display in the list of
templates to choose from during the campaign composition stage, so
it is important that the name makes sense to the person writing the
campaigns.
In this case we called the template phpList announcements,
because it is the template we use when we announce a new version
of phpList. We have different templates for community news and
phpList hosted special offers, for example.
name your template and upload it
Upload your file
To add your template you can paste the html into the editor, or
upload it as a file. In this example we are uploading it.
Click the Browse button, locate the template file on your computer
and click Open. The file name will then appear next to
the Browse button (as shown in the image above).
Save your template
Scroll to the bottom of the page and click Save changes, using the
checking tools if you wish.
save your new template
Upload your logo?
The next screen gives you an opportunity to upload your template
images, if you have any. This will usually be a logo. In this case the
logo is hosted remotely and so no image is listed to upload.
add images to your template, or not
Click Save images.

118

Your template will now be added to your list of Existing templates.
If you wish to set this template as the default for all campaigns, you
can check the button under CAMPAIGN DEFAULT.
a new template

Defaults and settings
There are some default settings for templates and footers
at Config > Settings under campaign settings.
For example you can choose which template will be used by default
by referring to its ID.
specify default template phpList
The ID of the template can be found next to the template name when
you go to Campaigns > Manage campaign templates from the
main menu.
template ID phpList

119

USING YOUR TEMPLATE
During campaign composition, use headings and other formatting as
normal. You do not need to apply any additional styling such as text
colour, if those elements are dealt with in your template.
compose ready for template
In the Format of the send campaign workflow, select your template
from the Use template dropdown.
format tab of compose process choose template
The template and theme are then applied during sending.
template is applied

FEEDBACK
Discuss this chapter here.

120

20. MORE TEMPLATE
PLACEHOLDERS
This chapter contains additional details that may be useful for a
designer who is creating a template for use in phpList.
[SUBJECT]

[SUBJECT] adds the subject of the email within the newsletter text.

[CONTENT] - a mandatory placeholder
This is where the message's content (body) will be inserted. Every
template must have a [CONTENT] placeholder.

[FOOTER]
The message footer

[SIGNATURE]
[SIGNATURE] prints the phpList image signature.
[FORWARDURL]
[FORWARDURL] is replaced with the personalised URL only. To use
this, you will need to wrap it in HTML, like this:
Forward to a Friend
[PREFERENCESURL]
[PREFERENCESURL] allows the recipient to edit their subscribe
preferences, for example update their email or the number of lists
they belong to. This essentially allows them to maintain your list up to
date for you and is an invaluable feature.

[UNSUBSCRIBEURL] - a mandatory placeholder
[UNSUBSCRIBEURL] allows the recipient to totally unsubscribe from all
your lists. In phpList you must include this placeholder somewhere in
your body or footer. It is best to use this along side
[PREFERENCESURL] if you manage multiple lists, so subscribers can
leave just one list rather than all lists if they want.

[DOMAIN]
Prints your domain, e.g. yourdomain.com as listed in your
configuration settings.

[EMAIL]
Prints the subscribers email address;

SOME OLDER PLACEHOLDERS
121

These are some older placeholders which still work, but are not
recommended for use:

[FORWARD]
[FORWARD] is a link where the recipient can go to “forward this
message”. The default text for this placeholder is this link.
For example, if you use "If you want to forward this message to a
friend click [FORWARD]", it will come out as:
[UNSUBSCRIBE]
Like Forward the link that subscribers can use to unsubscribe. It will
also be replaced with "This Link", which means you can use it like this:
To unsubscribe from our newsletter click [UNSUBSCRIBE]
[PREFERENCES]
Like Forward and Unsubscribe the link that subscribers can use to
update their personal details and preferences. It will also be replaced
with "This Link", which means you can use it like this:
To change your preferences click [PREFERENCES]

FEEDBACK
Discuss this chapter here.

122

21. DIY: SUPER SIMPLE
TEMPLATE
We have made a very basic template for you to use. You will also
need
A version of your logo or similar image measuring 300px wide.

DOWNLOAD AND SAVE THE TEMPLATE
Download the template by clicking here and then saving the file to
your PC.

UPLOAD THE TEMPLATE TO PHPLIST
Go to Campaigns > Manage campaign templates.

Click add new template.

Give your template a name, for example My Newsletter Template.
Then click Browse.

123

Select the file you downloaded earlier, called basic-template.html,
from your computer and click Open.

Then click Save Changes.

124

UPLOAD YOUR LOGO TO PHPLIST
You will then be directed to add your logo. Remember, it must be no
more than 300 pixels wide. Click Browse.

Select your logo file from your computer and click Open.

125

Click Save Images.

MAKE THE TEMPLATE YOUR DEFAULT?
You will see your new template added to your list of existing
templates. If you will use this template for most of your campaigns,
click the radio button under Campaign Default.

COPY THIS FOOTER TEXT
Update your preferences | Unsubscribe

Add the footer to phpList
First go to Config > Settings.

126

Then scroll down till you find the Campaign Settings area.

Click the edit icon

Delete the contents up to the -- and right-click to Paste in the html
you copied from this chapter.

127

Click Save Changes.

Any new campaigns will now use this footer by default.

USING YOUR NEW TEMPLATE
Compose a new campaign. In this example I have pasted the html
from my latest blog.

128

Check that you are using your template by clicking Next and
examining the Format tab.

Send a test message using the Send test box at the bottom of the
page.

129

Take a look at the email when it arrives. You will notice your logo
displays even when other, remote images are blocked, because
phpList has sent it as an attachment.

And you can see your template has been applied,

130

FEEDBACK
Discuss this chapter here.

131

22. SUBSCRIBE PAGE
DESIGN AND CONFIGURATION
Subscribe page is the name of the page where your subscribers can
join your lists. You can have as many subscribe pages as you want,
and you can make them look like your website.
You can customize your subscribe pages in various ways. You can edit
the default design, which will affect all the pages, on your Config >
Settings page, and/or you can tweak the design of individual pages
using the Header and Footer boxes on the subscribe page editor.

MODIFICATIONS FROM WITHIN THE
CONFIG > SETTINGS PAGE
Go to Config > Settings from the main menu, and scroll down to
the subscription-ui settings area. Here you can edit the html of
the pages, and also a few basic settings.

MODIFICATIONS FROM WITHIN THE
SUBSCRIBE PAGE EDITOR
The Header and Footer boxes in the General Information section
of Config > Subscribe Pages > add/edit a page can be used to edit
the HTML of an individual subscribe page.
The html in these boxes is generated from the defaults in
Config > Settings > subscription-ui settings, which can also be
edited (see above).
You don't need to use   etc, as phpList already
includes this for you. However, you can add your own Meta Tags and
CSS file links or your own  just so long as all these extras are
above the .
If you create your own CSS styles for your page, save the file outside
of the phpList folder structure, for example in the stylesheets
directory. Then add a rel link to the new file above the  tag.
Keeping it outside of the phpList folder structure will make it easier to
upgrade later on.

ADVANCED CUSTOMISATION
You may wish to heavily customise of your Subscribe page, to make it
look like it is part of your website (rather than third party software).
You should use a HTML editor for this task. You create a blank page in
your HTML editor, then copy and paste the contents of the Header
box and replace the code   in the HTML editor with
the copied code.
132
You will need to be careful with exactly how much you paste into the
Header box and whatever you do paste must fit within the 
below the 
FEEDBACK
Discuss this chapter here.
133
23. ADVANCED CAMPAIGN
STATISTICS
This chapter covers
The statistics menu
Drilldown by campaign into clicks and/or opens
Domain statistics
Using a Google tracking code
Forward to a friend.
Basic statistics, as found in the Statistics Overview, are covered in the
chapter called Basic Campaign Statistics.
THE STATISTICS MENU
The statistics menu pulls together a lot of features. It is worth
exploring what can be found though this menu. The main items on
the menu are Overview, Opens, Campaign clicks, URL clicks and
Domain statistics. You may also see other options, for example
Advanced statistics, if you statistics plugins is activated.
To get a basic understanding of what data is available you can work
methodically from the top down, first viewing each page, then seeing
what links are provided in each page, and onwards. You will often
come full circle.
In this chapter we will approach our drilldown from analysing one
campaign, covering both opens and clicks. You can also compare
multiple campaigns, or focus on a specific URL you are trying to drive
traffic to. The approach you take depends on the questions you are
trying to answer.
DRILLING DOWN INTO AN INDIVIDUAL
CAMPAIGN
The starting point for an analysis of a single campaign is the
campaign statistics overview. This can be found in Campaigns > List
of campaigns > Sent Campaigns by clicking on the graph button
134
and also by visiting Statistics > Statistics overview and clicking
on the name of the campaign.
Either of these routes will bring you to the Statistics Overview for a
campaign. The page gives you an overview of information and two
ways to drilldown are available.
Opened Drilldown
135
By clicking the number of opens, you can get a a page called Open
Statistics.
This page allows you to Download as a CSV file a list of those
subscribers who were registered as having opened the campaign
(remember this is by no means everyone, only those recorded).
The csv file can in turn be used to create lists of active subscribers, or
by using the list-exclude feature you can isolate inactive subscribers
too.
You can also click on an individual subscriber to drilldown to the
subscriber level.
136
This will take you to the Campaigns tab in the History section of the
Subscriber profile, where you can click further links to view the
campaigns they have opened (left) or the links they clicked on in that
campaign (right).
You can also see the date on which they viewed a campaign and the
response time (in seconds).
Clicked Drilldown
In your campaign statistics overview page, you can also choose to
drilldown into clicks data.
137
This will take you to a list of the links in that campaign, and how many
people clicked on each one.
138
If you click on the url you can see how many people clicked on that
url across all campaigns which contained it.
That data can also be downloaded as a csv.
139
DOMAIN STATISICS
The Domain statistics page is accessible from the main statistics
menu and it is a fascinating page which can give you real insight into
the nature of your subscribers.
USING A GOOGLE TRACKING CODE
Using a Google tracking code ensures that any visits to your website
from the campaign are recorded in Google Analytics, if you have
Google Analytics tracking installed on your site.
Google tracking is quite different to the in-built phpList opens/views
tracking. Firstly the data is not collected, stored or viewed in phpList.
Also, if you link to another website in your campaign and if that
website also has Google Analytics tracking on their site (which is
likely) then they also receive data. In that sense the tracking code is
not exclusive to you.
To turn on Google tracking for an individual campaign, click the add
Google Analytics tracking code in the Finish tab of the campaign
workflow.
140
To turn on the use of tracking codes for every campaign, use the
Always add Google tracking code to campaigns in your
campaign settings area, which can be accessed from Config >
Settings.
To view the data in your Google Analytics go to Acquisition >
Campaigns and you will see the name of each campaign.
141
FORWARD TO FRIEND
On your Statistics > Statistics overview page, the third column,
FWDS, shows the number of people who have forwarded the mail
through the phpList ForwardToFriend system.
This system uses a placeholder to create a link or form in the email
body or footer of your campaign for your subscribers to use to
forward the mail to someone else.
If your subscribers use this method to forward your campaign, any
actions (clicks, forwards etc) taken by the new recipient will be
included in your campaign statistics separately.
It is possible for you subscribers to forward the message by other
means, but you cannot reliably tell: any clicks or opens in an email
which has been forwarded without the Forward to a Friend system will
be recorded as actions of the original subscriber.
It is therefore worth including an option to forward the campaign,
using the [FORWARDURL] placeholder, in the header or footer. For
example,
using forward to freind feature in footer of phpList
The subscriber will then see a forwarding link in the email footer:
forward link in footer, phpList
When a subscriber clicks this link they are prompted to enter an
email:
forward to freind system, phplist. enter an email
FEEDBACK
Discuss this chapter here.
142
INSTALLING AND
UPGRADING
24. INSTALLING PHPLIST MANUALLY
25. INSTALLING USING AN AUTOINSTALLER
26. CONFIGURATION: VERIFY SETTINGS
27. UPGRADING A MANUAL
INSTALLATION
28. UPGRADING AN AUTO-INSTALLED
INSTALLATION
29. COMMON INSTALLATION ERRORS
143
24. INSTALLING PHPLIST
MANUALLY
This chapter explains how to manually install phpList. You may wish to
install it using an automated tool if one is available to you. See the
auto-installation chapter for more information on this.
OVERVIEW OF PHPLIST INSTALLATION
phpList lives in its own folder called "lists." Manual installation follows
these steps:
Download phpList
Unzip phpList
Upload to your server using FTP
Create a database
Add the database details to the config.php file
Configure using web interface.
DOWNLOAD PHPLIST
First download the latest version of phpList from
http://www.phplist.com/download by clicking either Download ZIP or
Download TGZ.
The link will take you to SourceForge, where your download will begin
after a few seconds. Depending on which browser you use, you may
be asked to click Save before the download starts.
UNZIP PHPLIST
Once you have downloaded phpList to your computer, unpack it to a
temporary folder. You can usually do this by right clicking and
choosing Extract Here (Linux, as in screenshot), double clicking the
folder (mac) or right click "extract all" (Windows).
144
UPLOAD TO YOUR SERVER USING FTP
Start your favourite FTP program, in this case we are using FileZilla.
Browse though to your temporary folder in the FTP program, then
open the public_html folder to find the lists folder.
145
Upload this /lists folder into your public_html file on your server. This
folder may have lots of files in it already. In the image below you can
see the public_html folder on the server contains folders for a
WordPress site.
GRAB A COFFEE!
This upload may take some time, you may even have to split it over a
number of partial uploads depending on your connection speed, time
outs and upload limits.
CREATE A DATABASE USING YOUR
CONTROL PANEL
Once you have uploaded the /lists directory, go to your hosting
control panel and create a database. If you need help, your web
hosting company can help you with this.
Whatever the process, you will always end up with three things:
A database name, for example cl52-phplist
A database username, for example phplist
A password for your database, for example T!LcDaM/4
146
An example of creating a database
These screenshots provide an example. This may or may not be
similar to the way you can create a new database on your server.
That depends entirely on which software your hosting company uses.
First click MySQL Databases.
Then type in the new database name (we used the name phpList) and
enter or generate a strong password. Make sure you keep a copy of
these details!
This system creates a user automatically, where the username is the
same as the database name (a common preference). In other
software you may need to add a new user separately and you may
also need to allocate this user to your database.
Your database is now ready. Copy down the details because you will
need them in a moment.
147
EDIT THE PHPLIST CONFIG.PHP FILE
Next, you need to put the details of your new database into your
configuration file.
Browse your temp folder on your computer and go to lists > config
> config.php. Load and edit this file in a text editor, such as Notepad
(windows) TextEdit (mac) or Geany/Kate/Geddit/etc (linux).
Never use a word processor program (like Microsoft Word), it will only
generate formatting and disruption.
Your freshly downloaded config.php should look something like this:
148
There are four places where you need to replace the word in "quotes"
at the end of a line of code with something specific to your server:
# what is your Mysql database server hostname
$database_host = "localhost";
If you do not know what to enter here, you will either need to use trial
and error, or ask your hosting provider what to put here. If you want
to keep things simple, ask your hosting provider.
Trial and error:
You may be lucky in that your server allows "localhost" for your
$database_host entry, in which case you don't need to make a
change (this was true in our example below). The second option to try
is "127.0.0.1".
149
If these fail you will receive an error towards the end of installation. If
both of these fail then this entry must be something specific to your
server. GoDaddy and 1&1 servers are pretty specific, for example.
# what is the name of the database we are using
$database_name = "phplistdb";
Replace the phplistdb with the name of your database that you set
up earlier. In our example below this is cl52-phplist.
# what user has access to this database
$database_user = "phplist";
Replace the phplist with the name of your databse user you set up
earlier (this may be the same name as your database). In our
example below this is also cl52-phplist.
# and what is the password to login to control the
database
$database_password = 'phplist';
Replace the phplist with the password you created. The password in
the example below is obscured.
Test mode in phpList: ("TEST",0)
One other thing you will need to do, either now or at some point in
the future, is to change the value of TEST in this file. Until you do this,
your install is essentially in "sandbox" mode, and will not fully function.
By default test is defined ("TEST",1). Change this to define ("TEST",0)
to be able to send messages out.
This is done automatically in the auto installers.
Config_extended.php
You may need to add some extra lines to your config.php. These
extra lines are ready made for you in config_extended.php, which is in
the same directory as config.php. Simply copy the lines you need and
paste them below the others in config.php
SAVE AND UPLOAD
150
Once you have edited the config.php file you need to save it and
upload this new version to your server. This can be done in the same
way as your initial upload: open your ftp client, find the
lists/config/config.php file on your pc and then upload it to
lists/config/config.php on your server.
GO TO YOUR INSTALLATION
Open your web browser and go to your installation. This is located at
http://mywebsite.co.uk/lists/admin.
If you get an error saying that the database has not connected, then
check your config.php file again: a tiny error such as a space
before/after your database name/password will stop this from
working.
When you see the grey and black interface with the phpList logo at
the top, you are in the right place.
THE FINAL STEPS
Click Initialise Database and fill out the form.
151
Click Continue
If you would like to email phpList to let us know you are using the
software, click Tell us about it.
We recommend that you sign up to receive email
announcements about new versions of phpList. You can enter
your email and click Subscribe. If you do not want to sign up,
for example because you are already on the list, then click Do
not subscribe.
Finally click to continue with phpList seutp.
152
YOU'RE DONE!
You have now finished installation, and the next step is configuration.
FEEDBACK
Discuss this chapter here.
153
25. INSTALLING USING AN
AUTO-INSTALLER
SOFTACULOUS, FANTASTICO, ETC
If your web provider offers Softaculous, Fantastico or other similar
software installers, then you may choose to use the. These installers
do the bulk of the work for you and can be faster than installing
phpList manually.
Log on to your web space, (cPanel/Plesk etc) and click on
Softaculous/Fantastico then find the
phpList installation and choose the Install option. Please note, for
this example I have used Softaculous installer.
On the Install page you can choose your settings. In the order shown
in the image:
Protocol http:// is the norm
Domain if you have more than one domain on your hosting/web
space, choose that here
Directory you should set the directory that you wish your
phpList installation to be placed in. This should usually be left
blank however in this example we are using test/phplist1. Any
variations will become part of the URL to your phpList install, so
it is best to keep it simple
A database name is suggested next. You may change it within
limits to a name that makes more sense to you if you wish. 8
characters are usually the maximum here as it will be prefixed to
your hosting username (eg:user234_phplst1 in my example).
Important! If you have only one database available to all your
websites, then it is very important to use a unique identifier here, one
that makes sense to you as belonging to this phpList installation. If
you have access to a number of databases, then it's an advantage to
use one per installation.
154
Ignore the settings for the Cron job for the time being, there is
some information on this in a later chapter
Site Settings: chose the name for your site, and change the
default Table Prefix if you wish
Finally, enter your username (admin by default), user password,
make it a good strong one. Real name and email and then click
on the Install button.
Wait for it to complete installing your phpList and you will get a final
page offering the links to the public "front end" and the Admin "back
end"
That's it, you've installed phpList with Softaculous or Fantastico.
One final thing to remember is that if you install phpList using this
method, you can update phpList to a later version in a matter of
minutes via the Update option offered in Softaculous/Fantastic. Do
however make a backup of your config/config.php file before starting
the update especially if you have customised your settings.
FEEDBACK
Discuss this chapter here.
155
26. CONFIGURATION:
VERIFY SETTINGS
The configuration process starts after installation when you see this
screen:
This chapter deals only with the Verify Settings instruction, because
attributes, lists, subscribe pages and subscribers are dealt with in
other chapters.
The Settings page discussed in this chapter is normally accessed
through Config > Settings There are lots of settings you can
change at any time, however, it's good to have an overview after
install.
To start your settings verification click Go there next to Verify
settings in your configuration overview, or navigate to Config >
Settings from the main menu.
Please note you do not need to click save for every item, keep editing
and click save just once at the end.
GENERAL SETTINGS
These settings will have been completed for you during installation.
This example is taken from a personal website/blog.
156
If any of these is incorrect, change it by clicking on the edit icon:
[WEBSITE] placeholder
Once you have set your website address, it will be used to complete
the [website] placeholder if you use this in your template or content.
SECURITY SETTINGS
Checking for new versions:
It is important that you keep your installation secure: this means
keeping it up todate. This setting, defaulting to 7 days, is how often
your phpList will check for updates. When you are notified of a new
version, you should update as soon as you can.
157
REPORTING SETTINGS
These settings establish who will be notified, by email, of events in
your phpList install. These include system messages, such as
notices of new subscribers, or reports such as when your campaign
sending starts and finishes.
It may be that you have a team of people or just an individual, some
standard emails, like name@mydomain.com, or specific secondary
accounts, like phpList_admin@mydoimain.com.
You can change these settings any time, but it's good take some time
to decide how you want to manage your system now.
158
You can also choose to send yourself notifications about subscriptions
among other things. To edit this setting click the edit icon, choose
Yes from the dropdown and click save changes.
CAMPAIGN SETTINGS
This section specifies many of the defaults for your campaigns, for
example, which email to display in the From: line of your campaigns
(the sender).
159
While you can change some of these options during the composition
of each individual campaign, they will always display as stated here
during the next new campaign.
If you will often use the same details, it is simpler and safer to specify
them correctly here so you don't need to remember to add/edit these
details every time you send a new campaign.
The settings regarding html template and the default footer are dealt
with in the chapters about templates.
TRANSACTIONAL SETTINGS
These are the settings for the automatic emails that get sent by
phpList to your subscribers when they perform an action. For
example, when they subscribe or change their details. The emails in
this section are usually noreply@mydomain.com.
160
Noreply is used because it is common for subscribers to reply to these
emails, for example asking to be unsubscribed. Subscribers should be
encouraged to use the automated processes provided by phpList,
which can unsubscribe them without any additional work by the list
manager (you!).
In addition to specifying the email addresses to be used for
transactional messages, this section also deals with the content of
these emails. These are ready-made for you, however, you may wish
to customize them to reflect your circumstances or brand identity.
If you do this, make sure not to remove any of the important
information included in the default messages, especially the
placeholders in [square brackets].
161
SUBSCRIPTION-UI SETTINGS
This section deals with the design of subscribe pages. This section is
dealt with in the chapters on subscribe pages.
SEGMENTATION SETTINGS
This section allows you to edit your list category organization. This is
dealt with in the chapter about categories.
SUBSCRIPTION SETTINGS
This section provides you with the links to various functional pages
within your phpList install. Most of the time you should not edit these
settings. They provide a useful reference.
COMPOSITION SETTINGS
This area changes depending on which plugins you are using, and has
some useful tweaks for your WYSIWYG editor. For example you can
specify the width of the editor. This might be useful if you plan to
compose your campaigns on a tablet computer or smart phone.
YOU'RE DONE!
162
You should now see a green thumbs up next to your settings
verification. Don't forget, you can come back to this page at any time
to update your settings, and refer back to this guide for help.
If you wish carry on with the rest of your set up, see the chapters
corresponding to each item in the list, for example attributes or
adding subscribers.
FEEDBACK
Discuss this chapter here.
163
27. UPGRADING A MANUAL
INSTALLATION
You should upgrade your phpList installation frequently. By keeping
up-to-date you can take advantage of the latest features in phpList
which will make your work easier and help you advance your work.
Often, a new version will include security updates which are important
to protect your data, and the personal details of your subscribers.
Upgrading from phpList 2 (orange) to 3 (grey) works well - if you are
still using phpList 2 please upgrade as soon as as you can.
OVERVIEW
If you installed phpList manually, this is the correct installation
method for you. The process consists of the following steps:
Download the new version
Unzip the files
Back up your database
Back up your config.php
Replace old version on your server with new version
Replace new config.php with your back up
Upgrade database with automated updater
WHEN TO UPDATE
You can sign up for email notification about new versions of phpList
by subscribing to our announcements list.
When normal configuration/settings have been maintained, phpList
will check for updates every 7 days. You can adjust the frequency of
checks on the Config > Settings page, accessed via the main menu.
When a new version had been released you will receive a notice on
your dashboard.
You can navigate to your Dashboard from any page in phpList by
clicking the link at the top of the Navigation sidebar.
If you see a notification saying "A new version of phpList is
available!" then it's time to upgrade.
164
DOWNLOADING THE NEW VERSION
From your Dashboard notification, click Download.
This will take you to phpList.com/download, where you click
DOWNLOAD ZIP or DOWNLOAD TGZ.
You will be redirected to SourceForge, where your download will start
after a few seconds.
Choose a place on your computer to store the file and click Save
(your own operating system/browser may work differently).
165
UNZIPPING PHPLIST
Once you have downloaded phpList to your computer, unzip it. You
can usually do this by right clicking and choosing Extract Here
(Linux, as in screenshot), double clicking the folder (mac) or right click
"extract all" (windows).
166
Next you must back up your installation, this is a vital step as it will
keep your data safe is anything goes wrong with the upgrade process.
BACK UP YOUR DATABASE
The method of doing this will depend on your hosting provider. In this
example we use cpanel. Click on the MySQL Databases icon.
Locate your phpList database and click Backup.
167
Choose to Save File and click OK.
Choose a location on your computer to save your database too, and
click Save.
168
BACKING UP YOUR CONFIG.PHP
You also need to back up your config.php., which is usually located at
public_html/lists/config/config.php on your server. You will need
this file again later.
You can do this using an ftp client. In screenshot below we used
filezilla and the config.php file was simply dragged and dropped onto
into the backup folder.
169
If you have customized/altered any other files for some non-standard
scenario you should back them up too.
UPLOAD THE NEW VERSION
Next you need to upload the new version files to replace the files
from the previous version. You can do this using an ftp client. This is
similar to installing for the first time. In the screenshots below we
used filezilla.
First we selected all the files within the public_html/lists folder on
our pc, then we uploaded them to the public_html/lists folder on our
server.
170
You need chose to overwrite all files.
REPLACE NEW CONFIG.PHP WITH YOUR
OWN
Now you need to replace the new config.php file with the one you
backed-up earlier, which has your system details already set up.
171
We did this using an ftp client.
UPDATE YOUR DATABASE
Finally, log in to your instillation (http://yourdomain.com/lists/admin).
You will see a big red box at the top of the screen telling you to
upgrade your database. Click Upgrade.
Read the text, and click Upgrade.
172
You will see a progress bar, and when the process has finished you
will be told that you have successfully upgraded.
FEEDBACK
Discuss this chapter here.
173
28. UPGRADING AN AUTOINSTALLED INSTALLATION
Auto Installer Upgrade.
Providing you have used your web based auto installer
(Softaculous/Fantastico) to initially install your phpList, you can simply
update it by visiting the installers page and click on the upgrade link.
NB: This will only appear when an update is available.
Simply click the green upgrade icon and let the system upgrade your
installation. Once completed, simply restore your customised files and
the upgrade is complete.
FEEDBACK
Discuss this chapter here.
174
29. COMMON
INSTALLATION ERRORS
POSSIBLE ERRORS
ERROR 500:
The .htaccess file must be present in the lists/ directory and must
contain the line "DirectoryIndex index.php" as this ensures phpList
looks for index.php rather than the default index.htm(l).
Also because this file tries to be all things to all servers, if you get an
Error 500 report when first running phpList the issue could be that
there are lines that start "php_value" they have a better than 50:50
chance of crashing your installation with the dreaded Error 500. In
this case, either remove the lines completely, or add a hash "#" to
the start of any lines beginning with php_value (so it would look like
this #php_value) and resave the .htaccess file.
MYSQLI ERROR:
If you receive an error referring to mySQL or mySQLi then you need
to change this line "$database_module = "mysql.inc";" to
"$database_module = "mysqli.inc";" the line in question is around
700-710 of the full config.php file
From version 5.5 of PHP, the mysql_ functions have been deprecated.
FEEDBACK
Discuss this chapter here.
175
SENDING
30. METHODS OF SENDING (BROWSER,
CRON, COMMAND-LINE)
31. SETTING UP YOUR CRON
32. SCHEDULING
33. SENDING A WEB-PAGE
34. SENDING PLAIN TEXT
35. BOUNCE MANAGEMENT
176
30. METHODS OF SENDING
(BROWSER, CRON, COMMANDLINE)
Setting up phpList for sending is a complex topic, there are many
(many) variables, most of which which are out of the control of
phpList developers, such as your hosting provider and server
configuration.
In our early chapters, we have assumed that you are sending from
the browser, to a small list, and that your phpList has been configured
already.
How sending works
Once your campaign is ready, you need to tell phpList to send the
campaign. There are two steps to this:
1. Submit the message to the queue.
When creating the campaign, the last tab of the workflow is the
'SEND' tab. Pressing the 'start campaign' button submits the
campaign to the sending queue.
2. Process the queue, either manually via the browser or command
line, or automatically via a cron job or remote queue processing
system.
MANUAL SENDING USING THE BROWSER
This is the simplest way to send. You must:
Leave the browser open while your process the queue
Leave your computer active (not asleep) while you process the
queue
Be aware that your hosting provider may not allow emails to be
sent this way by default, or may suspend your account if you
send volumes which breach their terms and conditions.
This method of sending works essentially as described in the chapter
on Sending your first campaign. Using the default configuration file
settings, either click the Process Queue button which is presented
as the final step of the campaign workflow, or use the System >
Process queue option from the main menu.
Once you begin sending you must leave the browser open: if the
browser is closed while the message is sending, the queue processing
will stop. To continue sending where you dropped off, you will need to
open the browser, log into phpList, and "System"/"Process queue"
again, leaving the browser open.
177
The system will send the queue using the settings in your config file
(config.php), which controls the send rate, the envelope header, and
so forth. You should talk to your hosting provider about these settings,
they may want you to send in small batches or have a cap on the
number of mails you can send each hour.
PHPLIST.COM REMOTE QUEUE
PROCESSING
One way to bypass the issue of leaving your browser open without
creating a cron job is to use the phpList.com remote queue
processing system.
This means that once you click to process the queue, phpList.com will
keep your system sending after you close your browser: you are still
sending from your server, and according to the settings in config.php
- phplist.com just keeps your system "awake" for you.
You will be prompted to consider this process the first time you send.
If you have previously sent messages then
visit http://yourdomain/lists/admin/?
page=hostedprocessqueuesetup to get started.
You should see the following page.
Click Create Account.
178
This opens a window with a phpList.com page enabling you to create
a special phpList.com account. Fill out your details and click Create
account.
You then need to go to your email account and click the link in the
confirmation email.
179
Click Continue to go to your new account.
Click Generate new key to get your API key.
Copy the API key.
And paste it into your phpList installation, into the Enter the API key
here box on http://yourdomain/lists/admin/?
page=hostedprocessqueuesetup
180
Click Continue setup.
The process is now complete. When you add a message to the queue,
it will be processed according to your settings.
If you wish to disable this functionality in the future, go back to ?
page=processqueue and click the Reset Choice button.
181
Queue processing from a remote computer using a
secret (Config > Settings > Secret for remote
processing)
This is essentially the same system as above, but you don't use the
phplist.com service, you use another server of your choosing.
Documentation for this is here.
AUTOMATIC QUEUE PROCESSING USING
THE COMMAND LINE AND CRON JOBS
Background
A more advanced phpList configuration is to configure automatic
queue processing from the command line of the computer (shell
terminal). These are the most powerful ways of sending and they
have many advantages. However, setting them up can be
complicated for a variety of reasons including:
Restrictions of hosting companies, such as GoDaddy, Hostgator
and others
Features of your virtual machine (VM) hosting account
(In)Ability to ssh into the server to test commands
PHP settings configured by your hosting company
Working through a web based interface such as cpanel, or plesk
to test and setup the required exact commands needed
Limited access and permissions due to account type and user
limitations
Every hosting company sets this up a little differently, so require
a setup specific to your exact situation.
If you don't understand, or give up trying to understand all these
details, look for qualified third party support to configure this and/or
offer hosted solutions that include automatic queue processing.
The Command line
The core of setting up the automatic processing is the command line
that will 'do the deed'.
For queue processing, the general format is:
/usr/bin/php /home/mydomain/lists/admin/index.php -pprocessqueue c/home/mydomain/lists/config/config.php
Breaking this down:
/usr/bin/php This is the command that invokes php. Your path may
vary, as well as the exact php command ( php-cli or php-cgi). The
exact path to the php command will need to be changed to match
your system.
/home/mydomain/lists/admin/index.php This is the fully qualified
path to the index.php file in the /lists/admin directory of your phpList
installation, as seen by the php command (above). Getting this right
usually requires some experimenting, and/or asking your hosting
provider. The '/home/mydomain' part will need to be changed to
match the layout of your system.
182
-pprocessqueue This specifies the action that you want to perform
(processqueue)
-c/home/mydomain/lists/config/config.php This is the fully
qualified path to the config file with your settings. The
'/home/mydomain' part will need to be changed to match the layout
of your system.
Once you determine the exact command line that will process the
queue on your machine, then you need to run that command
periodically via a cron job (also called a 'scheduled task' in the cpanel
interface).
Setting up a cron job to periodically run the
Command Line
See the chapter "Setting up your Cron."
FEEDBACK
Discuss this chapter here.
183
31. SETTING UP YOUR
CRON
WHAT IS CRON
Cron is a time based task scheduler on Unix-like operating systems.
For more information check the Wikipedia page. This chapter will
describe how to set this up on Linux. On other Unix systems the set up
will be similar.
WHY SET UP CRON
When you set up the cron, two of the most time consuming parts of
phpList will become automated. These are processing the queue and
processing the bounces. Once you set up the cron, you will not have
to do these in your browser, but they will happen automatically.
Sending a campaign will become as easy as sending a normal email
from your desktop.
CAVEATS
The method described in this chapter requires the CLI version of PHP.
This may not be available on all systems. There are some "hacks" to
make it work with other versions of PHP, but this is non-intentional
functionality and therefore not described here.
STEP 1: SET UP COMMANDLINE
The easiest way to set up the cron is to set up a commandline script
that will handle all phpList commands. There is an example in the
"bin" directory in the phpList archive file.
Let's call the commandline script "phplist" and edit it with your
favourite text editor:
$ vi phplist
and type (or copy-paste) the content
#!/bin/bash
/usr/bin/php /home/website/public_html/lists/admin/index.php -c
/home/website/public_html/lists/config/config.php $*
You will need to change the above content to fit your system:
#!/bin/bash -> the shell that you want to use
/usr/bin/php -> the path to the PHP-cli commandline interpreter, this
can vary per system. Debian based systems (including Ubuntu) should
install the "php-cli" package.
/home/website/public_html/lists/admin/index.php -> the path to
your phpList installation, pointing to the index.php file in the admin
directory of phpList
184
/home/website/public_html/lists/config/config.php -> the path to
your config file
Once you have constructed your commandline file, place it
somewhere in your path, e.g. in /usr/local/bin and make it executable.
chmod 755 /usr/local/bin/phplist
From then on, you can process phpList on commandline, for example
with
phplist -pprocessqueue
STEP 2: SET UP THE CRONS
Once you have the commandline script, you can set up the crons with
your favourite cron editor. On Linux, you type "crontab -e" in order to
edit your cron entries.
0-59/5 * * * * phplist -pprocessqueue > /dev/null 2>&1
0 3 * * * phplist -pprocessbounces > /dev/null 2>&1
The above example will process the queue once every 5 minutes and
process the bounces once a day. That will be sufficient for most
systems.
The example also discards any output, which you will want to do. You
can always check the output by running the above commands
manually from the shell-prompt.
STEP 3: TELL PHPLIST
Once you've set up the cron and it is working, you can tell phpList and
some links will disappear. Put the following two lines in your config
file:
define ("MANUALLY_PROCESS_BOUNCES",0);
define ("MANUALLY_PROCESS_QUEUE",0);
This will hide the links to process the queue and bounces from the
phpList interface.
NOTES
There's no danger in overloading your server. When a second queue
processing command is activated when the previous one is still active,
phpList will detect this and bail out. Therefore there will always be one
active queue sending process at any time. This is also important to
ensure that the sending limits, set with Batch processing, will be
honoured.
FEEDBACK
Discuss this chapter here.
185
32. SCHEDULING
In the campaign workflow you will find the scheduling tab.
If you want to send a campaign straight away, and there is no need to
stop sending before a specific time, then you can leave these details
unchanged and your campaign will simply send.
If your needs are more complex, read on.
Important information
Scheduling settings interact with your sending method. If you are only
able to process your queue from within the browser because you
have no cron or command-line access, then the embargo time
feature will not work for you. To send a campaign from the browser
you must always open your browser to process the queue and keep it
open until you have finished, even if you have used an embargo time.
SCHEDULING TAB
Below is an image of the scheduling tab. We we will work though it
from top to bottom:
SERVER TIME
The server time may not be the same as your local time. All of the
times in the scheduling page are relative to server time. Changing this
time is an advanced feature.
EMBARGOED UNTIL
The campaign will not be sent until this time has passed. If you have a
campaign which you wish to send at a later date, perhaps when you
out of the office or away from your desk, then this is the feature you
should use.
Embargo time is initially set to the nearest hour before you started
your new campaign: this effectively switches off the embargo feature
by default. To use the feature you must set the time in the
future. Simply set the date and time to the time you want to send,
relative to your server time which is stated above. Then place the
campaign in the queue as normal. If you are using a cron job then the
campaign will automatically start sending at the desired time.
186
STOP SENDING AFTER
This feature is used when the topic of a campaign is time sensitive,
for example, a special offer with an expiration date or an event with a
specific time. If the campaign would become irrelevant to anyone
who received it after a particular time, then this is the feature you
should use.
The primary use of this feature is when your list size exceeds your
sending capacity within the timeframe you need to send your
campaign in. For example, if you have a list of 10,000 subscribers and
can send 1000 emails in an hour but the campaign becomes
irrelevant in 8 hours time, you need to stop sending before everyone
on your list has received a copy of the mail.
Re-Queue
The re-queue setting is used to send a campaign to subscribers who
join a list after the campaign is sent. Remember, a campaign will
never be sent to the same subscriber twice.
As an example, you create a monthly newsletter on the first of
January, and send it to a list. Over the month you expect another 50
people to sign up, or be added to your list manually, and you would
also like them to automatically receive a copy of the campaign. You
would set up your campaign to re-queue every day and to requeue until 31st of January.
FEEDBACK
187
Discuss this chapter here.
188
33. SENDING A WEB-PAGE
To send a web page rather than a message to your subscribers, log in
to your phpList admin pages, then choose to Send a Campaign
Admin>Campaigns>Send a Campaign
From this page, click on Send a New Campaign (or edit an existing
Campaign). In this example, I'll use Send a New Campaign.
This results in:
Choose Send a Webpage rather than Compose message and you
should see this:
189
In the send a web page - URL box, enter the path of the webpage you
wish to send. Click outside the box and the URL is validated.
If you get this message, then check and double check that the page
you have entered actually exists. The URL does look correct, but the
page does not in fact exist.
Once the page to be sent has been validated, simply select the
template for your message (optional), the list to which you wish to
send to (required), check that the embargo time is correct and send
the campaign out.
Display Issues
Be aware that most email readers, especially those web-based ones
(Hotmail/Outlook, Gmail etc) will not show images by default, it will be
up to your subscribers to decide if they wish to receive images in
emails by (usually) clicking on a link in the email reader. Don't assume
that your images will automatically appear, so make sure your
webpage includes ALT Text for each image in your page when
designed.
FEEDBACK
190
Discuss this chapter here.
191
34. SENDING PLAIN TEXT
phpList always generates a plain text version of your campaign, which
is then included in the html campaigns as a matter of course. This is
part of the normal working of email functionality. phpList also gives
you two additional features:
Your subscribers can choose to receive plain text emails only
You can edit the plain text version to improve it.
You can see the plain text version embedded in the source of your
email by clicking View Source in your email client (exact instructions
vary wildly)
As you can see there is a plain text version in and amongst the html
and other code.
WHY EDIT THE PLAIN TEXT VERSION?
192
The automatically generated plain text version may not be very
attractive. It is good practice to provide a quality plain text version
because it:
displays better in some email software
makes your emails more accessible for people with visual
impairments.
To assess the state of your default plain text version, you can click to
view your emails only in plain text. In a desktop email client this is
usually View > Message Body As > Plain text.
You can then see your email as it would be displayed to someone who
is only able to receive plain text messages.
To improve this email and send a version formatted especially for
these subscribers only takes a few extra moments and, as you can
see, provides a much better quality of message.
193
Enabling plain text editing
Some installations do not show the Text tab, which is used to
manually configure your text-only email content. If your tabs look like
this, you'll need to change the configuration:
To activate the Text tab in your installation, add the following lines to
your config.php file:
# 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
define('USE_MANUAL_TEXT_PART',1);
An extra tab will now display in your campaign workflow.
194
CREATE YOUR PLAIN TEXT VERSION
Once you've created your HTML version in the Content tab (tab 1)
click the Next button.
phpList click next
You should now be in the second tab, Text.
You can manually compose the plain text version, or you can
generate it automatically by using the generate from HTML
button. Some special characters in your html email may cause this
automatic generation to fail. You can paste your text into this tab if
you need to.
The empty Plain text version of message box will now contain a
text only version of your html message.
The content should be the same as the html version. However images
in the html version will automatically be removed and replaced by
text descriptions and urls are replaced by links. You can edit the
message further if required, to make it as attractive and legible as
possible.
195
Once you are happy with your plain text version, click Save and
continue editing button, at the bottom of the text editing box, and
carry on with testing and sending your campaign.
When you send tests, you will receive two emails, one text and one
html.
FORMAT TAB: ONLY SEND PLAIN TEXT?
On the format tab there is a radio button for sending in either HTML
or Text. Typically you will want to select the "HTML" radio button,
which sends a version of the message that each subscriber specified
when they joined your list.
However, if you want to send the text version of the message, select
the "Text" radio button. This will override the user preferences, and
send all subscribers the text version of the email.
FEEDBACK
Discuss this chapter here.
196
35. BOUNCE MANAGEMENT
INTRODUCTION TO BOUNCE
MANAGEMENT
Whenever an email is sent via the internet, regardless of the email
software used, the email is transmitted by an MTA (Mail Transport
Agent). In most cases the MTA is the internet provider’s SMTP mail
server, sending to the MTA of the email’s recipient, through
intermediary MTAs.
If the email cannot be delivered to its recipient, the last MTA that tried
to transmit the email generates an error email, called a bounce
message, which is sent back to the sender’s email.
Usually, this bounce message contains a specific error code that
explains why your email could not be delivered to its recipient.
phpList implements bounce management which handles these
bounce messages, and provides automatic actions depending on the
error code, like removing an incorrect email address.
SETTING UP BASIC BOUNCE
MANAGEMENT
Basic bounce management counts bounces and unconfirms a user
after a given number of consecutive bounces.
Setting your bounce address
In order to use bounce management, you need to provide an email
address where the bounce messages are sent to (e.g.:
bounce@example.com). This email address is usually called the
Return Path. Note that this email address will only be added to the
email headers, and will not be shown to your users.
Once you have set up your return path email address, you may edit
the config.php by adding the following:
$message_envelope = 'bounce@example.com;
By default this setting is commented out (it has a # in front so will not
be actioned).
You will need to uncomment it (remove the hash) and change the
email to reflect your new bounce email.
197
pop or mbox
phpList can fetch emails from the bounce mailbox via two protocols,
mbox protocol where mails are accessed directly within a folder on
the server, and pop3 protocol where mails are downloaded just like a
mail client program would do it. The latter one is usually the simplest
option, especially if you don’t host your phpList setup yourself.
You can specify which procotol to use in config.php with the following:
# This can be 'pop' or 'mbox'
$bounce_protocol = 'pop';
When accessing the bounce mailbox via mbox protocol, we need to
tell phpList where the mbox files are. Edit config.php and add the
following:
# when the protocol is mbox specify this one
# it needs to be a local file in mbox format, accessible to
your webserver user
$bounce_mailbox = '/var/spool/mail/listbounces';
When accessing the bounce mailbox via pop3 protocol, we need to
tell phpList which server provides the emails, and the username and
password for the mailbox in config.php like this:
# when the protocol is pop, specify these three
$bounce_mailbox_host = 'pop.example.com';
$bounce_mailbox_user = 'popuser';
$bounce_mailbox_password = 'password';
Additionally, you might want to set the default pop3 port and
encryption with the following line (standard config):
$bounce_mailbox_port = "110/pop3/notls";
Or enabling ssl on port 995 without verifying certificate common
name of the certificate:
$bounce_mailbox_port = "995/pop3/novalidate-cert"
Setting up mailbox purge
Unless you’re doing some tests, you would want to delete bounce
messages once they are fetched, so they won’t be counted twice:
198
$bounce_mailbox_purge = 1;
You may also want to delete messages from the mailbox that could
not be processed because they do not match a user in the system.
Messages are still downloaded into phpList, so it’s safe to delete them
from the mailbox.
$bounce_mailbox_purge_unprocessed = 1;
You can define how many bounces in a row it needs for a user to be
marked unconfirmed.
Be aware that deleting processed bounce messages from phpList with
advanced bounce rules will disable this functionality.
$bounce_unsubscribe_threshold = 5
DOWNLOADING AND PROCESSING
BOUNCES
Downloading and processing bounces can be handled in the user
interface under System > Process Bounces.
You may also setup a cron task to download and process bounces on
a regular basis, see the chapter about cron tasks.
In that case, you might want to disable the Process Bounces menu
entry by adding the following:
define ("MANUALLY_PROCESS_BOUNCES",0);
define('BLACKLIST_EMAIL_ON_BOUNCE', 1);
ADVANCED BOUNCE MANAGEMENT
Advanced bounce management enables the automatic performance
of various actions depending on the kind of bounce error code that is
returned by the MTA.
To enable it just add the following in config.php
define('USE_ADVANCED_BOUNCEHANDLING',1);
Once this is set up, you may proceed in the phpList interface to
System > Manage Bounces > List Bounces Rules
199
From there you may create new bounce rules, based on regular
expressions that will trigger phpList actions.
Regular expressions are sequences of characters that match a search
pattern. While this manual won’t explain the use of regular
expressions, we will analyse the examples given here.
Bounce emails generally contain a header and a mail body that may,
depending on the MTA that sent the email, give a reason why the
initial email could not reach its recipient.
An example bounce email could look like the following:
Final-Recipient: rfc822; someuser@example.com
Original-Recipient: rfc822;someuser@example.com
Action: failed
Status: 5.2.1
Remote-MTA: dns; mx1.example.com
Diagnostic-Code: smtp; 550 5.2.1 This mailbox has been
blocked due to
inactivity (UserSearch)
What we see here is the recipient’s MTA telling us that the user’s
mailbox is blocked, probably because it’s not been used for a long
while. There are some excellent articles about MTA responses on the
internet. Every MTA programme has its own return messages. Also,
you may have noticed that the return messages usually come with a
3 digit code, 5.2.2 in this example.
This code is the error code corresponding to the return message, but
some MTAs just give bogus codes, especially when they think your
email is spam.
Now let’s create our first bounce rule:
200
The regular expression could be the exact sentence the MTA return
message contained, in brackets.
Now phpList provides multiple actions that can be triggered if a
bounce email matches our regular expression:
Delete subscriber
Unconfirm subscriber
Blacklist subscriber
Blacklist email address
Delete subscriber and bounce
Unconfirm subscriber and delete bounce
Add subscriber to the do-not-send list and delete bounce
Add email address to the do-not-send list and delete bounce
Delete bounce.
In our case, we can assume that our subscriber’s email address
haven’t been used for a long while, and that it’s safe to unconfirm the
subscriber.
Now we have a choice between “unconfirm subscriber” and
“unconfirm subscriber and delete bounce”. The only real difference
between both options is that deleting the bounce message will also
remove it from bounce statistics (using the BounceStatisticsPlugin).
Once we finished our rule, we may add it and try it against our
bounces.
Back in phpList, we can check if our rule matches any of our actual
bounces, by going to System > Manage Bounces > Check
Current Bounce Rules.
201
The system will then tell us how many bounces are caught by our
rules.
Now you may have a big list of bounces that aren't caught by the rule,
and some of them are pretty similar to the rule.
We may have multiple bounce messages that could say “account is
disabled” or “This account has been disabled” which basically means
the same as “mailbox has been blocked due to inactivity” of our first
rule.
Way may create two other rules to deal with these bounces, or
improve our regular expression to match all these messages with the
same rule.
Regular expressions use the pipe symbol “|” as OR statement,
meaning the following regular expression:
(black|white) would match any text that has the words black or white
in it.
Now let’s improve our first rule by adding all our MTA return
messages that basically mean the same thing:
The actual regular expression I used here is:
(account is disabled|This mailbox has been blocked due to
inactivity|This account has been disabled|The email account that you
tried to reach does not exist|This is a permanent error * local delivery
failed)
Note that the * is a wildcard token that means there can be up to zero
characters between “This is a permanent error “ and “ local delivery
failed”.
This rule can now deal with any of these 5 return messages.
Good starter rule set:
202
RULES TO COPY
(Archived recipient.) Delete subscriber
(delivery error: dd This user doesn't have a yahoo.fr
account|This user doesn't have a yahoo.fr account) Delete
subscriber
(type=MX: Host not found) Delete subscriber. No mail records for
the domain.
(sorry, no mailbox here by that name|Mailbox
disabled|address not found in table|User mailbox is not
local|mailbox not allowed|Mailbox syntax
incorrect|RESOLVER\.ADR\.RecipNotFound) Delete subscriber
and bounce. No ambiguity here, we can also delete the bounce
message.
(account is disabled|This mailbox has been blocked due to
inactivity|This account has been disabled|The email account
that you tried to reach does not exist|This is a permanent
error * local delivery failed) Delete subscriber and bounce. Same
as above
(User unknown|Unknown user|Unknown address|No such
recipient|No such user|The email account that you tried to
reach is disabled|Recipient not found|Recipient
unknown|Invalid recipient|Address unknown|Recipient
address rejected) Delete subscriber and bounce. Same as above
203
FEEDBACK
Discuss this chapter here.
204
PLUGINS
36. PHPLIST PLUGINS
205
36. PHPLIST PLUGINS
Your phpList can be extended, adapted and customized by the use of
plugins.
You can:
Use plugins from the phpList plugin library, which are developed
by the phpList community
Develop your own plugin, or pay a developer to build it for you
Contribute your plugin back into the plugin library.
This chapter will show you how to install, enable/disable and delete a
plugin.
In the example used, we will change the choice of editor used in our
install by installing the CKEditorPlugin and disabling the fckphplist
plugin.
THE PLUGINS PAGE
To get to the plugins page from the main menu, click Config >
Manage plugins.
You will see a list of the plugins you currently have installed. To find
new plugin click the Find plugins link.
206
the plugin library will then open in a new page.
GETTING THE PLUGIN URL FROM THE
PLUGIN LIBRARY
Once you have clicked the Find plugins link, you will see the plugin
library. Scroll down or search to find the desired plugin.
In this example we are installing the CKEditorPlugin.
Right click on the Download link and choose the option to copy the
url. The wording of this option will depend on your browser: in this
case it reads Copy Link Location.
207
INSTALLING THE PLUGIN
Return to your phpList (it should be in the browser tab to the left of
the plugin library). Paste the url into the box labelled Plugin package
URL and click the Install plugin below.
You will see the plugin install. Click Continue.
TURNING PLUGINS ON AND OFF
Once you are on the plugins page, either from Config > Manage
plugins on the main menu, or after installing a plugin and clicking
Continue, you can turn plugins on or off.
208
A green thumbs up icon indicates that the plugin is enabled (on) and a
red thumbs down icon indicates that the plugin is disabled (off).
To disable (turn off) a plugin click on the green thumbs up.
This will now turn red: the plugin is now disabled.
209
DELETING PLUGINS
If you delete a plugin, you will lose any settings or data related to that
plugin. If you are not sure, it is better to disable rather than delete.
If you are sure you want to delete a plugin, click the delete icon on
the plugins page.
Then click OK to confirm.
FEEDBACK
Discuss this chapter here.
210
TRANSLATIONS
37. SETTING UP PHPLIST IN YOUR OWN
LANGUAGE
211
37. SETTING UP PHPLIST IN
YOUR OWN LANGUAGE
There are two "faces" of a phpList install, which can be set up in
different languages:
What the administrators see, when sending campaigns for
example.
What subscribers, or potential subscribers, see, for example
subscribe pages.
CHANGING LANGUAGE IN THE
ADMINISTRATOR INTERFACE
At all times, including before login, there is a language selector on the
right hand side of your phpList. This sets the language of the
administrator interface and is set to English by default.
To change this simply select your preferred language from the drop
down.
212
If this is the first time you have used the language this will take a little
time:
The phpList interface will then be displayed in your language to the
fullest extent possible: if there are some words missing or incorrectly
translated, you can improve the translation.
PUBLIC/SUBSCRIBER FACING LANGUAGE
You can set a default language for all subscriber facing pages, and/or
set the language of each subscribe page on a case by case basis.
If all of your subscribers are likely to speak the same language, for
example, German, then you can set German to be the default
language for subscribe pages. Then each new page you create will be
in German by default.
213
Default Subscriber facing language
To change the default language for all subscribe pages, change
english.inc to your language file. This file is found in lists/texts/.
The change is made in lists/config/config.php, right at the beginning of
the file.
# select the language module to use
# Look for .inc files in the texts directory
# to find your language
# this is the language for the frontend pages
$language_module = "english.inc";
Subscribe pages
If you send campaigns in more than one language then you can set a
different subscribe page for each language manually.
When you create a new Subscribe Page you can choose the display
language from the dropdown menu.
We suggest you name your list and the subscribe page, for example,
"Newsletter - in Danish" to help keep your pages and lists organised.
214
FEEDBACK
Discuss this chapter here.
215
TROUBLESHOOTING
38. TROUBLESHOOTING TECHNIQUES
39. GLOSSARY
216
38. TROUBLESHOOTING
TECHNIQUES
This chapter gives you some hints on how to troubleshoot a problem
in phpList.
WHERE TO GO FIRST
The first place to go for help is phpList.org, especially
phpList.org/users - this page has the most up-to-date list of support
resources and will guide you through the process of getting help step
by step.
DESCRIBING YOUR PROBLEM
One of the biggest barriers to problem solving is being able to
describe the problem clearly and in enough detail. There is a useful
article here to help you with that - it's especially worth a read if you
are "not very technical".
IF YOU HAVE AN ERROR MESSAGE
If you have an error message, try pasting it into a search engine. All
our forums and documentation are fully indexed by search engines,
and your solution is likely to pop up in the results.
DON'T GIVE UP!
If you have a problem that is hard to solve, it could be a "bug." In this
case, take a look at the bug reporting process described on the
community site - our developer team may be able to fix your problem
in the next version.
FEEDBACK
Discuss this chapter here.
217
39. GLOSSARY
FEEDBACK
Discuss this chapter here.
218

Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Title                           : phpList
Creator                         : 
Producer                        : wkhtmltopdf
Create Date                     : 2015:06:29 14:10:51+02:00
Page Count                      : 218
Page Mode                       : UseOutlines
EXIF Metadata provided by EXIF.tools

Navigation menu