Growing and using complex lists 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. 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. 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 11.879. That means we have 11.879 subscriber profiles in our system all together. 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 11.879. This is because we have not added any new subscribers, we have just created a list out of current subscribers. 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. 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. 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-not-send 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. 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. 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. 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. 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. Search for lists by name The lists page now includes a field to search for your lists. This saves time on installations with many lists. If you have categorized your lists, the search will be performed on the lists within the currently selected list category. Feedback You can discuss this chapter here. 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. 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: 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 Click the copy and paste list of emails button in phpList You will then see the following page: 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. 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 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: test7@example.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, test7@example.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 subscribers from the main menu Click Import by uploading a file with emails. You will then see the Import Subscribers From Text File page. 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. 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). 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. 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 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 subscribers from the main menu. Click the final option for import by uploading a CSV file with emails and additional data. 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. 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. 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. 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. 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. 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. 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 Select the lists to offer Select the attributes to use Transaction messages 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. 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 is Don't offer choice, default to HTML, where the box defaults to unchecked on the subscribe page. Although, you can check any other field. 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. 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). 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: 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. Add an AJAX subscribe box on your website To make it very easy for your subscribers to sign up, and stay on your website, you can add an AJAX form to your website. Step by step 1. Create a subscribe page that only requires the email address to be filled out.This means for HTML Email choice, select Don't offer choice, default to HTML and for Display Email confirmation, select Don't display email confirmation. Make sure the subscribe page has at least one list to subscribe to and do not select any attributes as a requirement. 2. Set the text to show when subscription was successful in your Settings page. 3. Use the following code on your website.
Members of the community forum have provided some useful insights regarding the website AJAX integration. You can find the discussion thread here. NOTE 1: Your subscribers will be automatically added to all the lists that you selected for the subscribe page. The ID of your Subscribe page is the one passed as a parameter in the URL, id=1 in the example's javascript For consistency, the ID in brackets in the list[11] input should be that of your Subscribers list, the one that the Subscriber page is configured for (see Config/Subscribe Pages) If your Subscribe page has attributes, especially required ones, they should be added to your