This plugin provides pages for advanced search (including attributes), applying a command to a set of subscribers, several reports of subscribers including subscriber history and subscriptions, and importing from the command line.
It also provides “list subscribe” and “list unsubscribe” placeholders to include in campaigns.
See the README file on the GitHub page https://github.com/bramley/phplist-plugin-subscribers
The plugin adds items to the Subscribers menu
This page lets you search for subscribers who
The search term for matching an email address or attribute can have more than one value by separating each value by '|' or by '+'.
Use '|' to select subscribers whose attribute value is one of a set of values.
For example if there is a select attribute that allows the subscriber to select their country then this search term will select subscribers who have selected United Kingdom, Germany or France:
United Kingdom|Germany|France
Use '+' to select subscribers whose attribute value has all of a set of values. This will be useful only for checkbox group attributes where a subscriber can validly have more than one value.
For example if there is a checkbox group attribute that allows the subscriber to select one or more interests then this search term will select subscribers who have selected writing, reading, and swimming: writing+reading+swimming
The search term can be preceded by a ! character to select subscribers who do not match the search term. For example to select subscribers who do not have gmail email address:
!gmail.com
The results of a search show:
Column | Content |
---|---|
Subscriber | The email address of the subscriber, which is a link to the Subscriber Details page. |
Confirmed | An icon is displayed if the email address is unconfirmed. |
Blacklisted | An icon is displayed if the email address is blacklisted. |
Attributes | Each attribute that has been selected is displayed in a separate column. |
HTML | Whether the subscriber should be sent HTML format emails. |
Lists | The number of lists to which the subscriber belongs. |
Campaigns | This shows three figures: the number of campaigns sent to the subscriber, the number which the subscriber has opened, and the number in which the subscriber has clicked at least one link. |
Attributes can be displayed as additional columns in the listing. The form shows only the first 15 attributes, with the attribute name truncated to 20 characters. If no attributes have been created then the selection form is not displayed.
The full set of results can be downloaded as a CSV file using the Excel icon.
You can apply an action
to a set of subscribers. The subscribers can be provided by copying/pasting, uploading a file, or a group of subscribers identified by a partial email address (such as a domain).
On the first page you select the action and enter the subscribers.
The second page displays the email addresses that will be actioned. You can then apply the changes or cancel.
For each action the plugin will filter the provided subscribers by selecting only those for which the action will have an effect:
The action to reset the bounce count does not delete any bounce records.
For the action to resend the confirmation request email, you can add some additional custom text.
This report shows records from the user_history table. Core phplist shows user history for each individual user but not an aggregated view. This is useful to see, for example, recent subscribers.
You can filter events in three ways:
Filter | Selection |
---|---|
All | Select all events and display in reverse chronological order, i.e. most recent first. |
Since | Select all events since the entered date and display in chronological order. The date may be entered in any format that PHP will recognise, such as 2011-10-01 or 1 Oct. |
Contains | Select all events whose summary, detail, or IP address contain the entered text and display in chronological order. The text may be a regular expression. |
The results show the details of each event:
Column | Contents |
---|---|
Event | The event id |
Subscriber | The email address of the subscriber, which is a link to the Subscriber Details page. |
Date | The date of the event. |
Summary | The summary of the event |
Detail | The detail of the event. |
IP address | The subscriber's IP address |
This page shows the number of subscriptions and unsubscriptions for each month.
The chart shows subscriptions by month for the periods in the result table. Each bar has up to three sections: active, blacklisted and unconfirmed. Together these add-up to the number of subscriptions.
A line showing the number of unsubscriptions per month is overlaid on the bar chart.
The results show
Column | Content |
---|---|
Period | The year and month. |
Subscriptions | The number of new subscribers during the month. This total is calculated using the 'entered' date in the user table. The value will be the sum of the next three columns: active, blacklisted and unconfirmed. |
Active | The number of subscribers who are now confirmed and not blacklisted. |
Blacklisted | The number of subscribers who are now confirmed and blacklisted. The subscribers did not necessarily change to blacklisted in this month. |
Unconfirmed | The number of subscribers who are unconfirmed. |
Unsubscriptions | The number of unsubscriptions. This value is different to the Blacklisted total as it reflects when the unsubscription occured rather than when the subscription occured. |
Total | Sum of the values for each month displayed for each column. |
This report validates all subscriber email addresses and lists any that are invalid. It uses the same email validation function as core phplist.
On the result page each email address is a link to the subscriber details page, from where the subscriber can be edited or deleted.
This report shows subscribers who have had no activity (viewing any campaign) within an entered period. The results show
This report shows subscribers who do not belong to any list.
This report lists the reasons entered when people unsubscribe.
The plugin provides placeholders to subscribe and unsubscribe from a list:
List subscribe
The placeholders include a parameter for the numeric list id, for example [LISTSUBSCRIBE:4]
The URL is of the format mysite.com/lists/?p=subscribe&pi=SubscribersPlugin&uid=xxxx&list=n
where the list parameter is the list id and the uid parameter is the uid of the subscriber.
When a subscriber clicks the link they will be added to the list.
List unsubscribe
The URL is of the format mysite.com/lists/?p=unsubscribe&pi=SubscribersPlugin&uid=xxxx&m=99
where the m parameter is the message id and the uid parameter is the uid of the subscriber.
When the subscriber clicks the link they will be removed from all lists to which the campaign was sent and to which they belong. In most cases that will only be one list, but when there are several then the subscriber is removed from them all.
Configuration
The text of the links can be customised on the Settings page in the Subscription settings group. Also, you can change the styling of the link by specifying additional attributes for the <a> element, such as a specific class or a custom style. For example
class=“myclass”
or
style=“color: #ea5b0c;”
The plugin provides a command line page to import a file of email addresses into phplist. The file must be in the format required for the core phplist function “import a csv file with email addresses and additional data” but with a few restrictions:
The command to run the import page is similar to this but adjusted for the location of phplist and the actual command to run php:
php /path/to/phplist/admin/index.php -m SubscribersPlugin -p import2 -c /path/to/phplist/config/config.php -l 1 -f /path/to/file/import.csv
where the f parameter provides the path to the file to be imported, and the l parameter provides the id of the list to which the email addresses should be added.
The plugin page simply calls the core phplist import processing and displays the output:
phpList version 3.3.1 © 2000-2018 phpList Ltd, http://www.phplist.com
Reading emails from file …..ok, 2 lines<script type=“text/javascript”>
var parentJQuery = window.parent.jQuery;
parentJQuery(“#progressbar”).updateProgress(“0,1”);
</script>
All the emails already exist in the database and are member of the lists
Subscriber data was updated for 1 subscribers
0 subscribers were matched by foreign key, 1 by email
Please raise any questions or problems in the user forum https://discuss.phplist.org/