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

ArgumentDefaultInfo
conditions nullDefine conditions
status nullThe status of the subscriber
having nulladditional HAVING statement for the SQL
orderby nullThe field which is used for ordering
order nullOrder direction
limit nullLimit the result
offset nullOffset the result
return_ids falseOnly return the IDs.
return_count falseReturn the number of matches.
return_sql falseReturn the SQL statement.
include nullOnly return subscribers with certain IDs.
exclude nullExclude subscribers with certain Ids.
fields nullDefine which fields are returned. Use ‘all’ to return all fields.
meta nullDefine which meta fields are returned. Use ‘all’ to return all meta fields.
lists falseSubscribers in certain lists
lists__not_in nullSubscribers not in certain lists
sent nullSubscribers who have received certain campaigns.
sent__not_in nullSubscribers who have not received certain campaigns.
sent_since nullSubscribers who received a campaign before a certain date.
sent__not_since nullSubscribers who have not received a campaign before a certain date.
open nullSubscribers who have opened certain campaigns.
open__not_in nullSubscribers who have not opened certain campaigns.
open_since nullSubscribers who opened a campaign before a certain date.
open__not_since nullSubscribers who have not opened a campaign before a certain date.
click nullSubscribers who have clicked certain campaigns.
click__not_in nullSubscribers who have not clicked certain campaigns.
click_since nullSubscribers who clicked a campaign before a certain date.
click__not_since nullSubscribers who have not clicked a campaign before a certain date.
click_link nullSubscribers who clicked a certain link.
click__not_link nullSubscribers who didn’t click a certain link.
unsubscribe nullSubscribers who have unsubscribed in a specific campaign.
unsubscribe__not_in nullSubscribers who have not unsubscribed from a specific campaign.
queue falseSubscribers who are queued for a specific campaign.
queue__not_in falseSubscribers who are not queued for a specific campaign.
s nullSearch string. Read more about the search below.
search_fields falseSearch only in certain fields.
strict falseUse strict mode on search
sentence falseThreat search as sentences and not as terms.
sub_query_limit falseProcess multiple sub queries. Read more

Conditions

The most powerful feature is 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 the role “Editor” exists.

Operators

Operators define in which relations conditions are.

Condition operators

ANDAll conditions must match.
OROne of the conditions must match

Fields operators

SignAlternativeDescription
=isIs equal
!=is_notIs not equal
<>containsContain certain character(s)
!<>contains_notDoes not contain certain character(s)
^begin_withEnds with a certain character(s)
$end_withIs Equal
>=is_greater_equalIs greater or equal
<=is_smaller_equalIs smaller or equal
>is_greaterIs greater
<is_smallerIs smaller
%patternMatches a regular expression
!%not_patternDoes 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 first name 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 a placeholder in your queries. While the asterisk matches any character the question mark only matches a single character.

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

Use the strict the 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 of what’s possible here are some examples:

Get all with the 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' => '2017-07-12',
		),
		array(
			'field' => 'rating',
			'operator' => '>',
			'value' => '50%',
		),
	),
));

Get all who opened the 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 longer and may require a lot of resources. The subscriber query has a sub_query_limit argument to limit the rows which are queried at once.

So instead of querying 500.000, you can query 2 × 250.000 or 5 × 100.000 depending on your setup. Mailster will merge 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 subscribers Mailster will split the query into 5 sub-queries with this setting.