Mailster Subscriber Query

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

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

Fields operators

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“, “search” OR “term” 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“, “search” OR “term” 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.