====== Segment ======
---- plugin ----
description: Provides segmentation of the subscribers to which a campaign is sent using subscriber attributes and fields.
author : Duncan Cameron
type :
compatible : phplist 3
depends :
conflicts :
similar :
tags :
sourcerepo : https://github.com/bramley/phplist-plugin-segment
donationurl:
----
====== Purpose ======
This plugin provides flexible segmentation of subscribers when sending a campaign.
It allows you to filter the subscribers based on attribute values and subscriber data:
* campaign activity
- was sent/was not sent a recent campaign or any campaign within a period
- opened/did not open a recent campaign or any campaign within a period
- clicked/did not click any link in a recent campaign or any campaign within a period
* Entered date (the date they signed-up to phplist)
* List entered date (the date they subscribed to one of the lists to which the message is being sent)
* email address
* subscriber id (the incrementing number assigned to each subscriber)
* subscriber unique id (the 32 character value assigned to each subscriber)
* List membership, belongs to ALL of the selected lists
* any attribute value
When the campaign is sent then only those subscribers who meet either any or all of the conditions will be selected.
The filtering of subscribers happens when phplist is actually sending the campaign. As phplist processes each subscriber it calls the plugin to decide whether or not to send to that subscriber. Therefore, when phplist starts to process a campaign it will appear that it is sending to the complete list because at that point it does not know which subscribers will be selected by the plugin.
To ensure that you understand this approach, you should send a test campaign to a small list to confirm that the correct subscribers are selected.
====== Installation ======
phpList now includes this plugin, which can be enabled on the Manage Plugins page.
See the README file on the GitHub page https://github.com/bramley/phplist-plugin-segment for how to configure the plugin or upgrade to the latest version.
===== Support =====
Please raise any questions or problems in the user forum https://discuss.phplist.org/
===== Translations =====
The text displayed by the plugin can be translated into other languages. See the file plugins/SegmentPlugin/lan/translations_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 translations_en.php to translations_xx.php, where xx is the language code, 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.
====== Usage ======
===== Add segment conditions =====
The plugin adds a tab to the Send a campaign page on which you can create segment conditions to filter the subscribers who will receive the campaign.
{{:plugin:segment.png?nolink&600 |}}
You can choose whether subscribers must meet all conditions or any of the conditions. Then add one or more conditions:
-select an attribute or a subscriber field from the drop-down list.
-the page will then refresh automatically showing a list of the operators for the selected field and a target input field.
-select an operator and then enter or select the target value
Any number of conditions can be created but usually one or two should be sufficient. Then click the Calculate button to see how many subscribers will be selected when the campaign is actually sent.
===== Calculating the number of subscribers =====
The plugin calculates the number of subscribers using the lists chosen on the Lists tab. It selects only those subscribers who belong to the lists and who meet either any or all of the conditions. Also, it excludes unconfirmed or blacklisted subscribers, any subscribers who have already received the campaign, and subscribers who belong to excluded lists.
A warning will be displayed if there are any incomplete conditions, where the target value has not been selected.
The calculation provides an idea of the number of subscribers using the current data. When the campaign is actually sent the plugin selects the subscribers again. Therefore, if there have been new subscriptions, changes to attribute values etc. in the interim, then the number of subscribers actually selected can differ.
==== On anniversary operator ====
This operator can be used when you have a date attribute holding the date of an event, such as birth date. It is used to send a campaign to subscribers on the anniversary of that date, such as the birthday. For this to work effectively you need to set the campaign to requeue each day and ensure that the queue is processed regularly, ideally using a cron job.
When you initially create the campaign and select this operator on the Segment tab the calculation of subscribers will include those whose anniversary is the current day. That will be accurate if the campaign is to be first sent on the same day, but the actual subscribers selected will definitely be different if the campaign is sent on a later day. It is still useful to see the number of subscribers for the current day in order to be confident of the calculation's accuracy.
==== After interval operator ====
When the "after interval" operator is used for the "Date signed-up to phplist", the "Date subscribed to list", or a date attribute, the calculation will include subscribers who meet the condition for **the current day**. That will be accurate if the campaign is sent on the same day, but the actual subscribers selected will definitely be different if the campaign is sent on a later day. Still, it is useful to see the number of subscribers for the current day in order to be confident of the calculation's accuracy.
The plugin displays the first 50 subscribers' email addresses to help confirm that the conditions have been specified correctly. The limit of 50 can be changed on the Settings page.
When the subscribers are displayed the full set of selected subscribers can be downloaded.
{{:plugin:segment4.png?nolink&600|}}
===== Processing the queue =====
When phplist processes the message queue the plugin selects the subscribers who meet the conditions for each message. It writes a record to the event log showing the number of subscribers selected.
{{ :plugin:segment5.png?nolink&600 |}}
===== Entering the target value =====
^Field / Attribute type^Entering the target value^
|textline, textarea, hidden attributes, email address, subscriber id and unique id|Entered directly in the text field.|
|select, radio button attributes|Selected from the multi-select list box.|
|Entered date and date attributes|A date is selected using the date-picker control. \\ An interval is entered directly in the text field and can be a number of days, weeks, months, quarters or years. For example ''15 days''|
|checkbox attributes|These do not have target values.|
|checkboxgroup attributes|Selected from the multi-select list box.|
|campaign activity|A prior campaign is selected from the drop-down list. The list contains only campaigns sent to the lists selected on the Lists tab. \\ For the "opened" and "did not open" operators the campaign activity also contains aggregated campaigns, any sent within the past 7 days, one month, or three months.|
==== Choosing target values from a multi-select list ====
The target values for select, radio button, and checkbox group attributes are presented as a multi-select list. When target values have not yet been chosen then the list will be displayed similarly to this
{{:plugin:multiselect1.png?nolink&400|}}
To show the list of values you need to click the area
{{:plugin:multiselect2.png?nolink&150|}}
Then you can select one or more target values, after which they will be displayed similarly to this
{{:plugin:multiselect3.png?nolink&400|}}
===== Evaluating conditions =====
^Operator^How the condition is evaluated^
|"is" and "is not"|The attribute value is compared directly with the target value.|
|"is blank" and "is not blank"|The attribute value is compared directly with an empty string.|
|"matches" and "does not match"|These operators use the mysql LIKE operator. This means that you need to include % or _ characters (sql wildcard characters) as necessary. See the [[http://dev.mysql.com/doc/refman/5.0/en/string-comparison-functions.html#operator_like|mysql reference manual]] for guidance on using the LIKE operator. \\ As an example, to match email addresses on the gmail.com domain the target value should be ''%gmail.com''|
|"REGEXP" and "not REGEXP"|These operators use the mysql REGEXP operator. See the [[http://dev.mysql.com/doc/refman/5.0/en/regexp.html#operator_regexp|mysql reference manual]] for guidance on using regular expressions in mysql. \\ As an example, to match email addresses on the gmail.com or yahoo.co.uk domains the target value should be ''(yahoo.co.uk%%|%%gmail.com)$''. \\ Or to select an arbitrary 20% of subscribers using the subscriber id field the target value could be ''[01]$''. This selects subscribers whose id ends in 0 or 1, which will select approximately 20% of subscribers.|
|"is included" and "is not included"|These operators test whether a subscriber email address is included or is not included in a set of email addresses. The target email addresses should be entered one on each line.|
|"is before" and "is after"|These operators compare the date part of the Entered date or attribute date with the target date, and test for being less than and greater than respectively. \\ Note that if you want to match subscribers who have subscribed since, and including, 1 January 2014 then the target date will need to be 31 December 2013 in order to include 1 January. |
|"is between"|This operator compares the date part of the Entered date or attribute date with two target dates, and tests for it being greater than or equal to the first value, and less than or equal to the second value.|
|"after interval"|This operator tests whether the current date is equal to the Entered date or date attribute plus the target interval. \\ It uses the mysql DATE_ADD function, see [[https://dev.mysql.com/doc/refman/5.5/en/date-and-time-functions.html#function_date-add|the mysql reference manual]] for information. The target interval can be only a number of days, weeks, months, quarters or years. \\ For example, using the Entered date and a value of ''1 week'' will select subscribers who subscribed exactly 7 days earlier. \\ The target value can be negative. This is useful only when a date attribute has a value in the future, and the plugin will select subscribers in advance of the date. \\ As another example, using a date attribute and a value of ''-1 week'' will select subscribers whose attribute value is exactly 7 days in the future.|
|"on anniversary"|This operator applies only to a date attribute and tests whether the month and day of month of the attribute value are the same as for the current day.|
|"is checked" and "is not checked"|These operators test whether the checkbox attribute is checked or not.|
|"one checked", "all checked", "none checked"|For a checkbox group these operators test whether the attribute value has at least one, all of, or none of the target values set.|
|"is one of", "is none of"|For a select list or set of radio buttons the operators test whether the attribute value is one of, or none of, the target values.|
|"was sent", "was not sent"|These operators test whether a subscriber was sent an earlier campaign.|
|"opened", "did not open"|These operators test whether a subscriber was sent an earlier campaign and, respectively, opened or did not open the email. \\ For aggregated campaigns, they test whether the subscriber opened or did not open any campaign sent within the chosen interval.|
|"clicked", "did not click"|These operators test whether a subscriber clicked any link, or did not click any link in an earlier campaign.|
|"Belongs to all selected lists"|This operator tests whether a subscriber is a member of ALL of the lists selected on the Lists tab.|
===== Empty or missing attribute values =====
The way that the plugin handles empty or missing attribute values varies slightly for each type of attribute and its operators.
^Attribute type^Missing, null or empty value^
|textline, textarea, hidden|Treated as an empty string. So, for example, the operator 'empty' will be true, and the operator 'not empty' will be false.|
|select, radio button|Treated as select list index of 0. So, for example, the operator 'is one of' will be false, and the operator 'is none of' will be true.|
|checkbox|Treated as being unchecked. So the operator 'checked' will be false.|
|checkboxgroup|Treated as all being unchecked. So the operators 'one checked' and 'all checked' will be false.|
|date|Values are ignored. So subscribers with these values will not be selected for any operator, 'is', 'is after', 'is before', or 'is between'.|
===== Saving and reusing segments =====
The current set of conditions can be saved for later use. Enter a name for the segment and click the Save segment button. If the segment name already exists then it will be replaced.
{{ :plugin:segment3.png?nolink&500|}}
Saved segments appear in a drop-down list, from which one or more can be selected. When selected the conditions will be added to any current conditions.
{{ :plugin:segment2.png?nolink&300|}}
A saved segment that is not needed any longer can be removed by editing a value on the Settings page within the Segmentation settings group. The field "Summary of saved segments" lists all of the saved segments. To remove a segment edit the field and delete the complete line.
===== A simple autoresponder =====
You can use the plugin to create a simple autoresponder for a date attribute by using the "after interval" operator to select subscribers whose attribute value is the specified number of days before the current date.
On the Schedule tab set the campaign to requeue every day and set the embargo time to be the time of day that you want it to be sent.
Use a cron job that runs at least once a day just after the embargo time to process the queue.
====== Configuration ======
The plugin adds a Segmentation group to the Settings page where you can enter:
* The size of the list of previous campaigns for Campaign activity. The default is 10.
* The number of selected subscribers to display. The default is 50 and the value must be in the range 5 - 500.
* The list of saved segments. You can delete saved segments but not rename or add.
====== Change Log ======
See the GitHub page https://github.com/bramley/phplist-plugin-segment