EasyMail Newsletter: For Developers

These instructions are not valid for version 1.x.

Index

Editing wp-config.php


You can add some constants in wp-config.php:

define( "ALO_EM_INTERVAL_MIN", 10 );

To modify the time interval between cron batch sending (in minutes, default: 5). To apply the change you have to reactivate the plugin.

define( "ALO_EM_DAYRATE", 1500 );
define( "ALO_EM_BATCHRATE", 30 );
define( "ALO_EM_SLEEPVALUE", 0 );

You can setup the cron batch sending using these constants. Respectively: Maximum number of emails that can be sent in a 24-hr period, Maximum number of emails that can be sent per batch, Interval between emails in a single batch in milliseconds. These constants override the values in Newsletter > Settings. Useful in a multisite installation or to force values regardless default limits.


Using plugin custom hooks


From version 2.5 the plugin package includes a mu-plugins folder that contains several file with custom hooks: move one or more of those files into wp-content/mu-plugins (if the directory doesn”t exist, simply create it) to activate them.

(Otherwise, as usual in WP, you can add your own code in functions.php inside your WP active theme folder).

The file already includes working features using custom actions and filters: eg. a placeholder to show a list of latest published posts, some email notifications when a newsletter is completely delivered and when there are new subscribers. You can use it as starting point for your development.

(The following lines are for old plugin versions, prior than 2.5)

The plugin package includes a php file called: alo-easymail_custom-hooks-sample.php.

You can use this file to add you custom code to the plugin: to make loading this file you have to rename it to alo-easymail_custom-hooks.php.

To avoid the loss of the file when you use the automatic WP upgrade, I suggest that you move the file into folder /wp-content/mu-plugins (if the directory doesn”t exist, simply create it).


Action & Filter hooks


The plugin has some action and filter hooks useful for developers. I suggest that you open files inside mu-plugins plugin folder to view some working samples.

Because newsletters are a custom post type you can use WordPress standard shortcodes, filters and actions to handle them.
To find all available hooks (including those not yet documented here…) in plugin code, look for: do_action and apply_filters.

about newsletter contents

alo_easymail_register_newsletter_args

filter Customise newsletter post type arguments when registered.

alo_easymail_newsletter_placeholders_table

filter Add custom placeholder to placeholders table in new/edit newsletter screen.

alo_easymail_newsletter_placeholders_title_{your_placeholder}

action Do some output in custom row in placeholders table; {your_placeholder} is your custom placeholder.

alo_easymail_save_newsletter_meta_extra

action Called when a newsletter is saved: useful to save custom placeholder or newsletter post meta.

alo_easymail_newsletter_title

filter To filter the newsletter title.

alo_easymail_newsletter_content

filter To filter the newsletter content.

alo_easymail_newsletter_headers

filter To filter the newsletter headers.

about newsletter events

alo_easymail_newsletter_delivered

action Do something when a newsletter delivery is complete.

about subscriber events

alo_easymail_new_subscriber_added

action Do something when there is a new subscriber.

alo_easymail_subscriber_activated

action Do something when a subscriber activates the subscription.

alo_easymail_subscriber_updated

action Do something when a subscriber updates own subscription.

alo_easymail_subscriber_deleted

action Do something when a subscriber unsubscribes.

about multilingual

alo_easymail_multilang_enabled_plugin

filter Manage the code of the enabled multilingual plugin (e.g. “WPML”).

alo_easymail_multilang_get_language

filter Manage the current language (e.g. “it”).

alo_easymail_multilang_get_all_languages

filter Manage available languages (e.g. array: 0 => “en”, 1 => “it”).

alo_easymail_multilang_translate_url

filter Manage the localised post url.

alo_easymail_multilang_translate_home_url

filter Manage the localised homepage url.

alo_easymail_multilang_get_subscrpage_id

filter Manage the ID of subscription page, usually called “Newsletter”.


Shortcodes


[ALO-EASYMAIL-PAGE]

On installation the plugin adds a page titled Newsletter: it”s useful for collect new subscribers and required to allow subscribers to manage their newsletter preferences. This page must contain this shortcode to work properly.

[ALO-EASYMAIL-ARCHIVE]

You can use this shortcode to show a list of selected newsletters in a page or post. You can pass some parameters to filter the search (to read available parameters and defaults: http://codex.wordpress.org/Template_Tags/get_posts).
In addition, you can pass 3 parameters:

  • newsletter_status
    the status of newsletter: “sent” (default), “sendable“, “paused;
  • ul_class
    the css class for the ul list tag: default is “easymail-newsletter-archive“;
  • li_format
    the format of the li list tags, concerning the presence of date and title for each row: “title_date” (default), “date_title“, “title“.
To show the last 3 sent newsletters, showing first date and then title:

[ALO-EASYMAIL-ARCHIVE numberposts=3 li_format=date_title]

To show the first 3 sent newsletters in alphabetical order, using a custom css class:

[ALO-EASYMAIL-ARCHIVE numberposts=3 orderby=title order=ASC ul_class="my-class"]

To show the newsletter now on sending:

[ALO-EASYMAIL-ARCHIVE numberposts=1 newsletter_status=sendable]

Functions


alo_easymail_print_archive()

You can use this function to print a html list of selected newsletters in a template file. You can pass an array with parameters to filter the search (to read available parameters and defaults: http://codex.wordpress.org/Template_Tags/get_posts). In addition, you can pass 3 extra parameters: go to ALO-EASYMAIL-ARCHIVE shortcode for details.
The function returns an array of post objects so you can do custom loops as shown in following samples.

To show the last 5 sent newsletters:
<?php
if ( function_exists("alo_easymail_print_archive") ) echo alo_easymail_print_archive();
?>
To show the newsletter now on sending, showing first date and then title:
<?php
$args = array ( "newsletter_status" => "sendable", "numberposts" => 1, "li_format" => "date_title" );
if ( function_exists("alo_easymail_print_archive") ) echo alo_easymail_print_archive( $args );
?>

alo_easymail_get_newsletters()

If you like to write your own loop you can use this function to get an array of post objects, that contains the selected newsletters. You can pass an array with parameters to filter the search (to read available parameters and defaults: http://codex.wordpress.org/Template_Tags/get_posts). In addition, you can pass a “newsletter_status” parameter: “sent” (default), “sendable“, “paused“.
The function returns an array of post objects so you can do custom loops as shown in following samples.

To show the last 5 sent newsletters:
<?php
if ( function_exists( "alo_easymail_get_newsletters" ) ) {
	$newsletters = alo_easymail_get_newsletters();
	if ( $newsletters ) {
		echo "<ul>\n";
		foreach( $newsletters as $post ) : setup_postdata( $post ); ?>
			<li><a href="<?php the_permalink(); ?>" class="homelist-title"><?php the_title(); ?></a> <span class="meta"><?php echo get_the_date() ?></span></li>
		<?php endforeach; 
		echo "</ul>\n";
		wp_reset_postdata();
	}
}
?>
To show the newsletter now on sending:
<?php
if ( function_exists( "alo_easymail_get_newsletters" ) ) {
	$args = array ( "newsletter_status" => "sendable", "numberposts" => 1 );
	$newsletters = alo_easymail_get_newsletters( $args );
	if ( $newsletters ) {
		echo "<ul>\n";
		foreach( $newsletters as $post ) : setup_postdata( $post ); ?>
			<li><a href="<?php the_permalink(); ?>" class="homelist-title"><?php the_title(); ?></a> <span class="meta"><?php echo get_the_date() ?></span></li>
		<?php endforeach; 
		echo "</ul>\n";
		wp_reset_postdata();
	}
}
?>

get_posts() / WP_Query

Because newsletters are a custom post type you can use WordPress standard functions, like as get_posts() or WP_Query class. Remember to use these search parameters: post_type equals to “newsletter”, post meta key equals to “_easymail_status” and a valid post meta value (“sent”, “sendable”, “paused”).


Examples and tutorials


1. How to add a custom placeholder: e.g. a list of latest published posts
in newsletter content

You can see a sample of custom placeholder inside plugin custom hooks (read about how to enable them).

Now you find a new available placeholder in new/edit newsletter screen: the [LATEST-POSTS] placeholder shows a list of latest published posts. You can use it as a tutorial for your development.


2. How to send a notification to admin when there is a new subscription

You can see a sample of custom placeholder inside plugin custom hooks (read about how to enable them).

Here you are the function:

/**
 * Send a notification to admin when there is a new subscriber
 * @param	obj
 * @param	int		user id optional: only if subscriber is also a registered user
 */ 
function custom_easymail_new_subscriber_is_added ( $subscriber, $user_id=false ) {
	if ( $user_id ) {
		$content = "A registered user has subscribed the newsletter:";
	} else {
		$content = "There is a new public subscriber:";
	}
	$content .= "\n\nemail: " . $subscriber->email ."\nname: ". $subscriber->name . "\nactivation: ". $subscriber->active . "\nlanguage: ". $subscriber->lang . "\n";
	if ( $user_id ) $content .= "user id: " . $user_id;
	wp_mail( get_option("admin_email"), "New subscriber", $content );
}
add_action("alo_easymail_new_subscriber_added",  "custom_easymail_new_subscriber_is_added", 10, 2 );

3. How to create a newsletter html/php theme

  • Go to alo-easymail-themes folder in plugin folder. (Tip: copy “alo-easymail-themes” folder into wp-content folder or into your theme directory and edit your themes there. Useful to prevent the loss of themes when you upgrade the plugin).
  • There you can find existing themes: look at them for inspiration and samples
  • Create an html/php theme file, called for example:
    myname_mytheme.html
  • If you need images for your theme, you have to store them in a folder named as the html theme file, e.g.:
    /myname_mytheme/
  • The src attribute of img tag must include relative url to images, e.g.:
    <img src=”myname_mytheme/image.jpg” />
    The plugin will replace automatically the theme folder name url (e.g. “myname_mytheme”) with the absolute url to theme folder (e.g. “http://yourblog.ltd/path/to/myname_mytheme”): so don”t use a theme name that contains your domain name or the replacement will break your images urls.
  • To include the newsletter main content you must include the [CONTENT] tag into the html theme file
  • Then, you can use all placeholders available for newsletters
  • Some guides for making html newsletters are listed in faq
  • Note that in Newsletters → Settings → tab Newsletter you can disable/enable themes, or force a specific theme as default

4. How to add automatically new subscribers to a mailing list

You can see a sample of custom placeholder inside plugin custom hooks (read about how to enable them).

Here you are the function:

/**
 * Automatically add a new subscriber to a mailing list
 * @param	obj
 * @param	int		user id optional: only if subscriber is also a registered user
 */ 
function custom_easymail_auto_add_subscriber_to_list ( $subscriber, $user_id=false ) {
	$list_id = 1; // put the ID of mailing list
	alo_em_add_subscriber_to_list ( $subscriber->ID, $list_id ); 
}
add_action ( "alo_easymail_new_subscriber_added",  "custom_easymail_auto_add_subscriber_to_list", 10, 2 );

Note that you have to do 2 things too:

  • leave the mailing list availability as “admin side only”: the subscribers cannot choose it;
  • insert the right $list_id inside the function: you can view the mailing list ids passing the mouse pointer over “edit” or “delete” icons in mailing list admin panel.

5. How to include the form in a template file

If you don’t want to use the EasyMail widget in your sidebar, here you are a quick hack to include the widget in a template file.

<?php
$istance = array( "title" => "Newsletter");
$args = array( "before_widget" => "<div class='my-class'>", "after_widget" => "</div>", "before_title" => "<h3>", "after_title" => "</h3>" );
the_widget("ALO_Easymail_Widget", $istance, $args );
?>

This example shows all available parameters.
Warning: be sure to not use the standard widget together this one. Because the widget ids are the same for both, the ajax calls won’t work properly.


6. How to avoid newsletter publishing on blog

The newsletter is a custom type of post: when you create a newsletter, it is available as a post on your blog.

From v.2.3 there is an option to publish or not newsletters online (see in Newsletter → Settings → tab General). When publication is off, the newsletter placeholders [READ-ONLINE] and [READ-ONLINE-URL] are useless.


7. How to add custom fields in subscription form

You can see a sample of custom placeholder inside plugin custom hooks (read about how to enable them).

There you can find a detailed guide about available fields and related parameters.
Here you are an example of a City text field:

function custom_easymail_set_my_custom_fields ( $fields ) {
 
	// Custom field: City
	$fields['cf_city'] = array(
		'humans_name'		=> __("City", "alo-easymail"),
		'sql_attr' 		=> "VARCHAR(100) NOT NULL",	
		'input_type' 		=> "text",
		'input_mandatory' 	=> true,
		'input_validation' 	=> false,
		'input_attr'		=> "maxlength=\"100\""
	);
	return $fields;
}
add_filter ( 'alo_easymail_newsletter_set_custom_fields', 'custom_easymail_set_my_custom_fields' );

Then, there is automatically a newsletter placehoolder for each custom field: e.g. cf_city => [USER-CF_CITY]


8. How to customise newsletter headers

You can customise the newsletter sender (email and name) in Newsletters → Settings → tab Newsletter. But you can rewrite all the newsletter headers, using a plugin filter hook. Here you are an example.

function custom_easymail_newsletter_headers ( $headers, $newsletter, $recipient ) {
	$headers = "From: Sender <sender@email.com>\n";
	$headers .= "Reply-To: Replyto <replyto@email.com>\n";
	$headers .= "Return-Path: Returnpath <returnpath@email.com>\n";
	$headers .= "Content-Type: text/html; charset=\"" . strtolower( get_option('blog_charset') ) . "\"\n";
	return $headers;
}
add_filter( 'alo_easymail_newsletter_headers', 'custom_easymail_newsletter_headers', 10, 3 );

9. How to insert a custom field in subscription form and add the subscriber to a related mailing list

I wrote a quick tutorial to insert a Country dropdown in EasyMail subscription form and to add the subscribes to a related mailing list. A subscriber selects “USA” as the country, it needs to be mapped to the “USA” mailing list.


10. How to add automatically new subscribers from other forms (e.g. Contact Form 7)

You have other forms in your blog where guests submit their data (including email) and you’d like to automatically subscribe them to newsletter.

If you are using custom forms, after checking data you can call the alo_em_add_subscriber function to create a new subscriber using submitted email and name. So you can write something like:

$fields['email'] = sanitize_email( $_POST["your-email"] );
$fields['name'] = sanitize_text_field( $_POST["your-name"] );
if ( function_exists ('alo_em_add_subscriber') && is_email( $fields['email'] ) )
{
	alo_em_add_subscriber( $fields, 1, alo_em_get_language(true) );
}

Otherwise, maybe you are using another plugin to collect info. In that case you should use the provided hooks to get the submitted data and use them to create new subscribers. For example, the following function add a new subscriber from submitted email and name in a form created with Contact Form 7 plugin. Please note that you have to edit the posted data labels with the names used in your CF7 form (“your-email”, “your-name”, “your-surname”).

function my_easymail_add_subscriber ( $cf7 ) {
        $fields['email'] = $cf7->posted_data["your-email"];
        $fields['name'] = trim($cf7->posted_data["your-name"]. " ". $cf7->posted_data["your-surname"]);
        if ( function_exists ('alo_em_add_subscriber') && is_email( $fields['email'] ) )
        {
		alo_em_add_subscriber( $fields, 1, alo_em_get_language(true) );
	}
        return $cf7;
}
add_action( 'wpcf7_before_send_mail', 'my_easymail_add_subscriber' );