larger smaller normal text version of this page
Phplist Documentation List and User functions

Import Users

Preparing import file

Field delimiter
You can import a list of email addresses and other user data from a CSV or Tab delimited file. Most database and spreadheet programs can produce a Comma delimited or Tab delimited text file. It is recommended to use "tab" instead of "comma" as a field delimiter, because your data is not likely to contain a TAB, and will therefore cause less trouble than files using the comma delimiter.

File size
The maximum size of the file you can import into phpList will depend on the memory limits of your server, but may not exceed 1Mb. If you need to import a larger file, you will have to split it up in smaller parts.

File structure

Email Firstname Lastname Hobby John Doe Fishing Karen Smith Athletics

While an email address is the minimum required field for importing a user list, you may choose to include other user data as well, like first name, last name, address, etc.
There are several structural requirements your import file should meet:
  • Make sure all the field names (headers) are in top row (first line) of the list.
  • The field name for the column containing the email addresses must be 'Email'.
  • Other field names must be exactly the same as the names of the user attributes you created in phpList . However, if you haven't yet created any user attributes in phpList , you may choose to let phpList create these automatically. In the latter case the attribute names will be based on the field names of the import file.

Importing users into existing lists

To import a list of email addresses, select 'Manage Users' from the admin page. Then select 'Import Users' from the list of options.
There are four ways to import existing information:
  • import emails with different values for attributes.
    • Use this option if you are importing a Tab-delimited text file (recommended) or CSV file that has the attributes for the users in the columns and one user per line.
    • If you are using attributes that already exist the attribute names must match exactly.
    • If you are using attributes that do not already exist they will be created automatically as "textline" attributes.
  • import emails with the same values for attributes.
    • Use this option if you are importing a simple list of emails (without attributes).
    • The import will utilize existing attributes defined in phplist.
    • You can specify the attribute values on the import form. The specified attribute values will be applied to all imported records.
  • import emails from an imap account.
    • This will search emails in your IMAP folders and add them. Only the Name of the person can be found as an attribute.
  • import emails from another database.
    • This option will allow importing users from another phpList database.

[more info needed on the above last 3 import methods]

Import options for "Import emails with different values for attributes"


If, for example, you have a list of email addresses, forenames and surnames -providing you have set up attributes called Firstname and Lastname- a typical import of such as spreadsheet would go like this:
  • Select the first option: import emails with different values for attributes.
  • Select the list to which you wish to add the email addresses.
  • Select a tab delimited text file containing your email addresses with the headings Email, Firstname and Lastname.
  • The defaults for field delimiter and record delimiter need not be changed, provided that these are the delimiters you use in your import file. However, if you are importing from an .ods or .xsl database, the recomendation is to save that file into a .csv and use TAB as Field delimiter and " " (double quotes) as Record Delimiter. That always works well.
  • Recommended: select 'Test Output' to check...
  • Show Warnings: select this, but expect warning due to Mantis bug:
  • Confirm the import, and the email addresses will then be added to the list.
The first import method, "Import emails with different values for attributes", is the one commonly used to import a user list with email addresses and additional data, like user names, addresses, etc. When using this import method you can use the following options.

File containing emails
Please enter the name of the file containing the data you wish to import.

Field Delimiter
The default field delimiter is a Tab. If your import file has a different field delimiter, you can specify it here.

Record Delimiter
The default record delimiter is a line break. If your import file has a different record delimiter, you can specify it here.

Test output
If you check "Test Output", you will get the list of parsed emails on screen, and the database will not be filled with the information. This is useful to find out whether the format of your file is correct. It will only show the first 50 records.

Show Warnings
If you check "Show Warnings", you will get warnings for invalid records. Warnings will only be shown if you check "Test Output". They will be ignored when actually importing.

Omit Invalid
If you check "Omit Invalid", invalid records will not be added. Invalid records are records without an email. Any other attributes will be added automatically, ie if the country of a record is not found, it will be added to the list of countries.

Assign Invalid
Assign Invalid will be used to create an email for users with an invalid email address.You can use values between [ and ] to make up a value for the email. For example if your import file contains a column "First Name" and one called "Last Name", you can use"[first name] [last name]" to construct a new value for the email for this user containing their first name and last name.The value [number] can be used to insert the sequence number for importing.

Overwrite Existing
If you check "Overwrite Existing", information about a user in the database will be replaced by the imported information. Users are matched by email or foreign key. When you import new records, phpList attempts to match them with existing records in the phpList database. Records will be matched in one of two ways:
  • If the field "foreign key" exists in your import file, users are matched by foreign key.
  • Otherwise, they are matched by email.
If you check "Overwrite Existing", when a match is found, information about that user in the database will be updated with the imported information. If you do not check "Overwrite Existing", when a match is found the record currently existing in the phpList database will remain unchanged. Your import data for that record will simply be discarded.

Note: If you check "Overwrite Existing" there is an interesting and potentially useful twist: If the records match, but a certain attribute for that record in the import file is blank, then the existing attribute for that record is retained. The same thing happens if that attribute is completely omitted from the import file--then phpList just leaves that attribute unchanged in any existing records. This is useful because it allows you to upload a file that changes certain attributes for users but leaves all the other unchanged. (Note: this is based on experimentation with phpList ver 2.10.2. Other versions may not work in this fashion.)
However, this phpList behaviour causes a potential problem: Lets say you have a membership list that you continually update and occasionally re-import into phpList using "Overwrite Existing". Let's say you had some data that you intentionally deleted from some records, say a person's phone number is no longer valid so you delete it. When you import this into phpList with the phone number field blank, phpList will then leave the "phone number" attribute for that field unchanged. (A possible solution is indicate records you wish to delete with a space or some other character?)

Retain Old User Email
If you check "Retain Old User Email", a conflict of two emails being the same will keep the old one and add "duplicate" to the new one. If you don't check it, the old one will get "duplicate" and the new one will take precedence.

This option only comes into play when the data you are importing includes a "foreign key" field.
  • Option Checked: If two users have the same foreign key, the email and associated attributes, list subscriptions, etc., for the entry currently in the phplist database will be retained with no change. A new database entry will be created with the imported information, list subscription, and attributes, with email address of the form "Duplicate xxx@yyy.zzz".
  • Option Not Checked: If two users have the same foreign key, the currently existing record's email address will be changed to the form "Duplicate xxx@yyy.zzz" but otherwise remain unchanged. A new database record will be created with the new email address, foreign key, attributes, and list subscription information.

Send Notification email
If you choose "send notification email" the users you are adding will be sent the request for confirmation of subscription to which they will have to reply. This is recommended in order to abide with opt-in regulations, and in addition it will allow you to identify email addresses that are no longer in use.

Notification throttle
If you are going to send a notification to users, you may want to add a little delay between messages. This can be useful if you need to comply with message limits imposed by your host. Please enter the number of seconds you want phpList to pause between emails. For instance, if you impose a pause of 10 seconds between messages, you will in fact send no more than 360 messages per hour.

Make confirmed immediately
If you are importing a list of emails of subscribers that have previously confirmed their subscription, you may prefer not sending a confirmation request email and instead make the users confirmed on import.

Overwrite Existing: More info about match via Email and/or Foreign Key

What is a 'foreign key'

If you use another ('foreign') database system to maintain you users list and want to synchronize that database with phpList 's users database, you can use the 'foreign key' field. A foreign key is a unique ID -usually generated in the foreign database system- which identifies a user record. When importing, phplist will first check if users in the csv file have a foreign key it can match with users in the phplist database. If so, it will use the foreign key ID to identify the user, instead of the email address as it normally would.
This has the advantage that if you are importing a lists of users, some of whom may have changed their email addresses in the mean time, phplist will be able to match the user's foreign key and update all other attributes, including the users' email addresses.
A bit of explanation about matching by email and/or foreign key:
  • the imported data has no "foreign key" field, then matching is done by email; if an existing record matches by email then it is considered a match whether or not that existing record has a foreign key.
  • if the imported data has a "foreign key" field, then matching is done by foreign key and no attempt is made to match via email. This could potentially result in two or more records with the same email address, and that problem is handled this way: records with duplicate email addresses are detected, and--depending on whether you have chosen "retain old user email" or not, either the newly imported or existing record is marked "Duplicate xxx@yyy.zzz"
Note: Be aware that this can create a problem in a situation like this: You have a phpList with some subscribers who are members of your organization and some who are just the general public. Your organization members have a foreign key but the general public do not. You periodically update your phpList information with fresh information from your membership list, including the foreign key so that a member always matches correctly. Now the problem arises when a general public subscriber joins your organization. Now that person has a foreign key and when the membership database is imported, match will be done via foreign key. So even though the email address matches, no match will be made. Depending on your setting of "retain old user email", either the existing or imported entry's email will be marked as "Duplicate xxx@yyy.zzz". Potentially you will then lose attribute information or list subscriptions for that user.

Reset import session
As you work your way along the import process you will see a link marked "reset import session". Use this if you want to go back to the beginning of the import process. You might want to do this because you are in the midst of working on an import and you want to abort and try again. Or if you are done with your import you can go back and try another.

This link is necessary because the import script keeps track of your state and you won't be able to get back to the start of the import process if you are in the middle of it--except via the "reset import session" link.

Advanced options
When importing you can include a column labeled "htmlemail" (formerly "Send this user HTML emails"). Values in the column can be 0 or 1. If 1, the user will receive email in HTML, if 0, the user will receive text emails. If blank, the user's existing setting for text/html will remain unchanged.

When importing you can include a column labeled "Is this account disabled?". Values in the column can be 0 or 1. If 1, the users account will be disabled, if 0, the user will be normal. This can help in situations like this: You maintain a membership list independent of phpList . Some people indicate to you that they don't want to receive email newsletters and you keep track of it via the membership list. Of course others unsubscribe via phpList. So now you have to reconcile the two. The way to do it would be, include a column in your import file "Is this account disabled?". Mark the records with a 1 that have indicated they want to receive no email newsletters. Leave all the other records blank in that column. When you import those with a 1 should be marked as disabled, while the blank records should be left in the state they were previously in. (It would be wise to test this first on your own phpList installation using a small test list.)

Configuration of the temp directory

Make sure you correctly configured the temp dir in config.php. Otherwise the file uploads will not work, and phpList wont be able to read the csv file.

This block in config.php:

# tmpdir. A location where phplist can write some temporary files if necessary
# Make sure it is writable by your webserver user, and also check that you have
# open_basedir set to allow access to this directory. Linux users can leave it as it is.
# this directory is used for all kinds of things, mostly uploading of files (like in
# import), creating PDFs and more
$tmpdir = '/tmp';

Tip & Tricks from the forum

Page was generated in 0.1023 seconds