Mailster offers an easy way to get your subscribers via segmentation. If you like to get more out of this via some custom coding you can use the Subscriber Query.

The Subscriber Query is made to get a list of your subscribers. It’s used internally everywhere where subscribers are needed.

Basic Usage

mailster( 'subscribers' )->query( $args );

This line will return an array of subscribers. The $args argument can have multiple parameters to adjust the results of your query. If you don’t use this option at all you’ll get all active (subscribed) subscribers.

The format of $args can either be an associate array or a query string. Both $args arguments are the same:

$args = array(
	'limit' = 10,
	'lists' => '3,6,8,9',
        'fields' => 'all',
	'meta' => array('timeoffset', 'form'),
);
$args = 'limit=10&lists=3,6,8,9&fields=all&meta=timeoffset,form';

Arguments

conditions (default: null)
Define conditions
status (default: null)
The status of the subscriber
having (default: null)
additional HAVING statement for the sql
orderby (default: null)
Field which is used for ordering
order (default: null)
Order direction
limit (default: null)
Limit the result
offset (default: null)
Offset the result
return_ids (default: false)
Only return the IDs.
return_count (default: false)
Return the number of matches.
return_sql (default: false)
Return the SQL statement.
include (default: null)
Only return subscribers with certain IDs.
exclude (default: null)
Exclude subscribers with certain Ids.
fields (default: null)
Define which fields are returned. Use ‘all’ to return all fields.
meta (default: null)
Define which meta fields are returned. Use ‘all’ to return all meta fields.
lists (default: false)
Subscribers in certain lists
lists__not_in (default: null)
Subscribers not in certain lists
sent (default: null)
Subscriber who have received certain campaigns.
sent__not_in (default: null)
Subscriber who have not received certain campaigns.
sent_since (default: null)
Subscribers who received a campaign before a certain date.
sent__not_since (default: null)
Subscribers who not received a campaign before a certain date.
open (default: null)
Subscriber who have opened certain campaigns.
open__not_in (default: null)
Subscriber who have not opened certain campaigns.
open_since (default: null)
Subscribers who opened a campaign before a certain date.
open__not_since (default: null)
Subscribers who not opened a campaign before a certain date.
click (default: null)
Subscriber who have clicked certain campaigns.
click__not_in (default: null)
Subscriber who have not clicked certain campaigns.
click_since (default: null)
Subscribers who clicked a campaign before a certain date.
click__not_since (default: null)
Subscribers who not clicked a campaign before a certain date.
click_link (default: null)
Subscribers who clicked a certain link.
click__not_link (default: null)
Subscribers who didn’t clicked a certain link.
unsubscribe (default: null)
Subscribers who have unsubscribed in a specific campaign.
unsubscribe__not_in (default: null)
Subscribers who have not unsubscribed in a specific campaign.
queue (default: false)
Subscribers who are queued for a specific campaign.
queue__not_in (default: false)
Subscribers who are not queued for a specific campaign.
s (default: null)
Search string. Read more about search below.
search_fields (default: false)
Search only in certain fields.
strict (default: false)
Use strict mode on search
sentence (default: false)
Threat search as sentence and not as terms.
sub_query_limit (default: false)
Process multiple sub queries. Read more

Conditions

The most powerful feature are conditions. They help you segment your subscribers even better. A simple condition looks like this:

array(
	array(
		'field' => 'form',
		'operator' => '=',
		'value' => '1',
	),
)

Which basically means “only subscribers who signed up via form with ID 1”.

array(
	array(
		'field' => 'lastname',
		'operator' => '^',
		'value' => 'a',
	),
	array(
		'field' => 'lang',
		'operator' => '=',
		'value' => 'en',
	),
	array(
		'field' => 'wp_capabilities',
		'operator' => '=',
		'value' => 'editor',
	),
),

This example returns only subscribers where the last name starts with “a”, the language is English and matching WP user with role “Editor” exists.

Operators

Operators define in which relations conditions are.

Condition operators
AND
All conditions must match.
OR
One of the conditions must match
Fields operators
= (is)
Is equal
!= (is_not)
Is not equal
<> (contains)
Contain certain character(s)
!<> (contains_not)
Does not contain certain character(s)
^ (begin_with)
Starts with certain character(s)
$ (end_with)
Ends with certain character(s)
>= (is_greater_equal)
Is greater or equal
<= (is_smaller_equal)
Is smaller or equal
> (is_greater)
Is greater
< (is_smaller)
Is smaller
% (pattern)
Matches a regular expression
!% (not_pattern)
Does not match a regular expression

Search

You can use the Subscriber Query to search your subscribers.

mailster( 'subscribers' )->query( array('s' => 'My search term') );

This will return subscribers with “My“, “searchORterm” in either their email address, hash, name or any custom field.

To force an AND connection use a plus sign before each term:

mailster( 'subscribers' )->query( array('s' => 'My +search +term') );

To search for exactly this phrase you can wrap it in double quotes:

mailster( 'subscribers' )->query( array('s' => '"My search term"') );

This will return subscribers with “My search term” in either their email address, hash, name or any custom field.

To limit the searched fields use the search_fields argument:

mailster( 'subscribers' )->query( array('s' => '"My search term"', 'search_field' => 'firstname') );

This will return subscribers with “My search term” in either their firstname field.

Exclude terms

You can include terms by prepending a ‘-‘ sign before the search term:

mailster( 'subscribers' )->query( array('s' => 'My search term -ugly') );

This will return subscribers with “My“, “searchORterm” in either their email address, hash, name or any custom field but not with “ugly” on one of these fields.

Placeholders

You can use “*” or “?” as placeholder in your queries. While the asterisk matches any character the questions mark only matches a single character.

mailster( 'subscribers' )->query( array('s' => '"My search term?"', 'strict' => true) );

Use the strict argument to search exactly for “My search terms” but not for “My search term“.

Searches can be very time consuming especially with a large subscriber base!

Examples

The possibilities with Subscriber Query are endless but to give you an idea what’s possible here are some examples:

Get all with surname “Doe” who signed up after 12th July 2017 and with a rating above 50%.

mailster( 'subscribers' )->query( array(
	'conditions' => array(
		array(
			'field' => 'lastname',
			'operator' => '=',
			'value' => 'Doe',
		)
		array(
			'field' => 'signup',
			'operator' => '>=',
			'value' => '2016-07-12',
		),
		array(
			'field' => 'rating',
			'operator' => '>',
			'value' => '20%',
		),
	),
));

Get all who opened campaign with ID 123 and clicked on a link ‘https://example.com’ or ‘https://www.example.com’

mailster( 'subscribers' )->query( array(
	'open' => 123,
	'click_link' => array( 'https://example.com', 'https://www.example.com' ),
));

Using Sub Queries

If you have many subscribers (500.000+) querying those subscribers can take long and may require a lot resources. The subscriber query has a sub_query_limit argument to limit the rows which are queried at once.

So instead of query 500.000 you can query 2 × 250.000 or 5 × 100.000 depending on your setup. Mailster will concat the results automatically and return the same array.

// get all subscribers with a subquery limit of 100.000
mailster( 'subscribers' )->query( array(
	'sub_query_limit' => 100000;
));

You can also define a filter so Mailster will always query with a sub query:

// define the sub_query_limit for all queries
add_filter( 'mailster_subscriber_query_args', function( $args, $campaign_id ) {
	$args['sub_query_limit'] = 100000;

	return $args;

}, 10, 2);

If you have 500.000 Mailster will split the query in to 5 sub queries with this setting.