User Tools

Site Tools

Translations of this page:

plugin:subscribers

Subscribers

—- plugin —-
description: Provides additional pages for managing subscribers.
author : Duncan Cameron
type :
compatible : phplist 3.x
depends :
conflicts :
similar :
tags :

sourcerepo : https://github.com/bramley/phplist-plugin-subscribers


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.

Installation

See the README file on the GitHub page https://github.com/bramley/phplist-plugin-subscribers

Usage

The plugin adds items to the Subscribers menu

Advanced Search page

This page lets you search for subscribers who

  • match an email address, user id or user unique id
  • have a specific subscribe page
  • match an attribute value
  • belong to a specific list
  • are unconfirmed or are blacklisted

The search term for matching an email address or attribute can be literal text or a regular expression.

Search using literal text

Subscribers are selected whose email address or attribute value contains the search term. For example yahoo will return email addresses that are on the domains yahoo.com, yahoo.co.uk, etc.

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

Search using a regular expression

The search term for matching an email address or a text attribute can be a regular expression, in which case the Regex checkbox needs to be checked. The processing described previously for the |, + and ! characters is not applied because that can be achieved through a regular expression.
For example the regular expression

\.[A-Za-z]{2}$

will match email addresses that have a two-character country code.

If the regular expression is invalid, such as incorrect syntax, then it will be rejected and the checkbox made unchecked. phplist will display the mysql error message above the search form.

Search results

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.
CampaignsThis 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.

Copy results to Command page

The plugin shows two buttons that will copy the search results to the Command page, allowing you to then apply an action to those subscribers.
The result of clicking the button is to display the plugin's Command page (menu Subscriber commands) with the email addresses of the first 1,000 subscribers from the search results shown in the text box.

Subscriber commands

Apply command to a group of subscribers

You can apply an action

  • confirm,
  • unconfirm,
  • blacklist,
  • remove from blacklist,
  • delete,
  • add to a list,
  • move between lists,
  • remove from a specific list,
  • remove from all subscribed lists,
  • resend confirmation request,
  • change the subscribe page
  • reset the bounce count on the subscriber's details
  • empty an attribute value

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:

  • confirm - subscribers who are not confirmed
  • unconfirm - subscribers who are already confirmed
  • blacklist - subscribers who are not blacklisted
  • remove from blacklist - subscribers who are already blacklisted
  • delete - all provided subscribers
  • move - subscribers who belong to the “From” list
  • remove from a specific list - subscribers who are already on that list
  • remove from all subscribed lists - subscribers who belong to at least one list
  • resend confirmation request - subscribers who are unconfirmed
  • change the subscribe page - subscribers who do not have the selected subscribe page
  • reset the bounce count - subscribers whose bounce count is greater than zero
  • empty attribute value - subscribers who already have a value for the attribute

The action to resend confirmation requests will send the emails immediately, without any batching or delay between them, unlike when sending a campaign.
You should send confirmation requests only for a small number of subscribers to avoid possible problems with exceeding your mail server's limits.
You can use the Invite plugin https://resources.phplist.com/plugin/invite if you have a large number of subscribers.

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.


Subscriber reports

Subscriber history


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:

FilterSelection
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
EventThe event id
SubscriberThe email address of the subscriber, which is a link to the Subscriber Details page.
DateThe date of the event.
SummaryThe summary of the event
DetailThe detail of the event.
IP addressThe subscriber's IP address

Subscriptions


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

ColumnContent
PeriodThe year and month.
SubscriptionsThe 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.
ActiveThe number of subscribers who are now confirmed and not blacklisted.
BlacklistedThe number of subscribers who are now confirmed and blacklisted. The subscribers did not necessarily change to blacklisted in this month.
UnconfirmedThe number of subscribers who are unconfirmed.
UnsubscriptionsThe number of unsubscriptions. This value is different to the Blacklisted total as it reflects when the unsubscription occured rather than when the subscription occured.
TotalSum of the values for each month displayed for each column.

Subscribers with an invalid email address

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.

Inactive subscribers

This report shows subscribers who have had no activity for campaigns sent to them within an entered period. The results show

  • the lists to which the subscriber belongs
  • the number of campaigns sent to the subscriber within the period
  • the total number of campaigns sent to the subscriber
  • the date of the most recent view of any campaign, not just those campaigns sent in the period (empty if the subscriber has had no activity)

The report selects subscribers who have been sent at least one campaign in the period, and have not opened any of those campaigns. Therefore it excludes subscribers who were not sent any campaigns in the period.

Note that the report can include subscribers who have not opened any campaigns sent within the period but have opened an earlier campaign.

This report can also be run from the command line, and can optionally blacklist or delete the identified inactive subscribers.
The command to run the report and save the results to a file on the web server is similar to this, where the f parameter is the path to the result file, and the i parameter is the report interval, which must be a valid mysql interval

php /path/to/lists/admin/index.php -p inactive -m SubscribersPlugin -c /path/to/lists/config/config.php -f /path/to/directory/inactive.csv -i "3 month"

To optionally blacklist or delete the inactive subscribers use an a option with either “blacklist” or “delete”

php /path/to/phplist/lists/admin/index.php -p inactive -m SubscribersPlugin -c /path/to/phplist/lists/config/config.php -i "3 month" -a blacklist
php /path/to/phplist/lists/admin/index.php -p inactive -m SubscribersPlugin -c /path/to/phplist/lists/config/config.php -i "3 month" -a delete

Subscribers who do not belong to any list

This report shows subscribers who do not belong to any list.

Unsubscribe reasons

This report lists the reasons entered when people unsubscribe.

Bounce count

This report lists the subscribers whose bounce count is greater than 0.

Consecutive bounces

This report lists the subscribers who have at least one consecutive bounce. It uses the same calculation as the core phplist processbounces page when it calculates consecutive bounces.

Consecutive bounces for a subscriber are counted from the most recent campaign in reverse order until a campaign did not bounce. Therefore if the most recent campaign did not bounce then the number of consecutive bounces is 0, even if an earlier campaign did bounce.

The database query to count consecutive bounces can take a long time to run if there are a large number of bounces to process. This report caches the query result so that paging forwards and backwards do not repeat the query. To explicitly re-run the query use the Refresh button.

Domain subscriber counts

This report groups all subscribers by email domain and lists the domains in descending order of number of subscribers. The Active column is the number of subscribers who are confirmed and not blacklisted.

Subscribers who have not confirmed

This report lists subscribers who have subscribed but not confirmed. It does not include subscribers who are unconfirmed for other reasons, such as consecutive bounces.

Placeholders

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]

  • [LISTSUBSCRIBE:n] which generates a link (an html A element)
  • [LISTSUBSCRIBEURL:n] which generates only the URL

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

  • [LISTUNSUBSCRIBE] which generates a link (an html A element)
  • [LISTUNSUBSCRIBEURL] which generates only the URL

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;"

Import from the command line

The plugin provides a page to import a file of email addresses into phplist. The page can be run from the command line or cron job, or as accessed as a remote page using curl.

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 file must use comma (not tab) as the field separator. Fields with embedded commas or double-quote characters must be enclosed by double-quotes.
  • the first line must be column headings
  • the heading of the column of email addresses must be 'email'
  • if used, the heading of the column of foreign keys must be 'foreignkey'
  • any additional columns will be treated as attributes and the column heading must match exactly the attribute name

The command to run the import page from the command line 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 curl command to run the import page as a remote page is similar to this

curl  -F list_id=2 -F import_file=@import.csv "http://mysite.com/lists/admin/?page=import2&pi=SubscribersPlugin&secret=xxxxx"

where the import_file parameter provides the path to the file to be imported, the list_id parameter provides the id of the list, and the secret parameter is the Secret for remote processing value from the Settings page

The plugin page simply calls the core phplist import processing and displays the output:

phpList version 3.3.1 (c) 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

Translate text

Admin pages

The text displayed on admin pages by the plugin can be translated into other languages. See the file plugins/SubscribersPlugin/lan/en.php for the English version that can be used as the basis for another language. Each line in the file contains the English text then the equivalent text in the target language.

To create a new language file, copy en.php to xx.php, where xx is the language code (such as “fr” for French), then change the texts for your target language.

You can share your new language file by submitting it for inclusion in the plugin. Please create a topic in the user forum or an issue on GitHub.

Public pages

The text displayed on public (or front-end) pages by the plugin can be translated into other languages. See the file plugins/SubscribersPlugin/lan/frontend_english.php for the English version that can be used as the basis for another language. Each line in the file contains the English text then the equivalent text in the target language.

To create a new language file, copy frontendenglish.php to frontendxxxxxxx.php, where xxxxxxx is the language (such as “french”) then change the texts for your target language.

You can share your new language file by submitting it for inclusion in the plugin. Please create a topic in the user forum or an issue on GitHub.

Support

Please raise any questions or problems in the user forum https://discuss.phplist.org/

plugin/subscribers.txt · Last modified: 2023/07/26 13:05 by duncanc

Resources
Contact Us

e: info@phplist.com

Boring Bit

phpList is a registered limited company

UK Company No. 07582966

VAT Registration 122 0788 37

© phpList 2016