Mailster for Developers - Mailster Knowledge Base

You can check for Mailster with

if( function_exists( 'mailster' ) ){
    // do stuff with Mailster
}

To run your code you should wrap it in the

Mailster Closure

The Mailster Closure ensures your code gets only executed if Mailster is completely loaded. If Mailster is not installed or activated it will simply be ignored.

add_action( 'mailster', function(){

   // add your custom coding here.

});

You can have multiple Mailster Closures in your plugin.

Adding new subscribers in Mailster is done with the “add” method of the subscribers class.

$subscriber_id = mailster( 'subscribers' )->add($entry, $overwrite);

$subscriber_id contains the ID of the inserted subscriber or a WP_Error object if it fails.

$entry can be a single email as a string or an associative array with field => values pairs

$overwrite overwrites the subscriber with the same email if exists

$subscriber_id = mailster( 'subscribers' )->add( array(
    'firstname' => 'John',
    'lastname' => 'Doe',
    'email' => '[email protected]',
    'status' => 1, //1 = subscribed (default) , 0 = pending, 2 = unsubscribed, 3 = hardbounced
    'custom-field' => 'Custom Value',
    'referer' => 'Your referer' //default = $_SERVER['REQUEST_URI']
    ...
), $overwrite );

To assign lists you can use the assign_lists method like

$success = mailster( 'subscribers' )->assign_lists( $subscriber_ids, $lists, $remove_old = false, $added = null );

$subscriber_ids is either a single id or an array with id’s of your subscribers

$lists is either a single id or an array with id’s of lists

$remove_old will remove all assigned lists before assigning the new one

$added timestamp when the user was assigned (true = current time)

$success is boolean

Lists

To work with lists you can use the Lists class with mailster( 'lists' )

Get a list of all lists

$lists = mailster( 'lists' )->get();

a list object looks like

( 
   [ID] => 2,
   [parent_id] => 0,
   [name] => 'WordPress Users',
   [slug] => 'wordpress-users',
   [description] => 'The description',
   [added] => 1411541385,
   [updated] => 1411541385
)

To get a single list add the $ID as the first argument:

$my_lists = mailster( 'lists' )->get( $ID );

Basic Example Integration

This is a quick example of how to implement a subscribe feature to your plugin

add_action( 'mailster', function(){

	// define to overwrite existing users
	$overwrite = true;

	// add with double opt in
	$double_opt_in = true;

	// prepare the userdata from a $_POST request. only the email is required
	$userdata = array(
		'email' => $_POST['email'],
		'firstname' => $_POST['firstname'],
		'lastname' => $_POST['lastname'],
		'custom-field' => $_POST['custom-field'],
		'referer' => 'Your referer',
		'status' => $double_opt_in ? 0 : 1,
	);

	// add a new subscriber and $overwrite it if exists
	$subscriber_id = mailster( 'subscribers' )->add( $userdata, $overwrite );

	// if result isn't a WP_error assign the lists
	if ( ! is_wp_error( $subscriber_id ) ) {

		// your list ids
		$list_ids = array( 123, 456 );
		mailster( 'subscribers' )->assign_lists( $subscriber_id, $list_ids );

	} else {
		// actions if adding fails. $subscriber_id is a WP_Error object
	}
});

Adding Subscribers from WordPress User

You can easily add new subscribers from an existing WordPress User with

$subscriber_id = mailster( 'subscribers' )->add_from_wp_user( $user_id, $userdata = array() );

$user_id is the ID of the WordPress user

$userdata is an optional array with user fields which overwrites the values from the WordPress user

$subscriber_id holds the ID of the inserted subscriber or a WP_Error object if it fails.

Unsubscribe a Subscriber

You can unsubscribe a subscriber via the unsubscribe method.

mailster('subscribers')->unsubscribe( $subscriber_id, $campaign_id = null, $status = null, $index = null );

$campaign_id (optional) is the ID of the campaign if you like to keep track of it.

$status (optional) define a status for this action (e.g. “manual unsubscribe”, “unsubscribed via custom action” to give some context.

$index (optional) is the number of the same $campaign_id if sent more than once (default = 0)

There are some alternative shortcuts too which work the same:

Unsubscribe by user hash

mailster('subscribers')->unsubscribe_by_hash( $hash, ... );

Unsubscribe by user md5 value of the email address

mailster('subscribers')->unsubscribe_by_md5( $md5_email, ... );

Unsubscribe by user email

mailster('subscribers')->unsubscribe_by_mail( $email, ... );