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.

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“, “date“.
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:
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“.
 

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 (direct link to the code hosted on Github: https://github.com/groucho75/alo-easymail/blob/master/mu-plugins/alo-easymail_latest-posts-placeholder.php ).

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.

$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 a language dropdown in subscription form

Sometimes you like that your subscribers select explicity their language. You can use this code: a new Language dropdown is added to subscription form and the value selected by the subscriber overrides the default language taken by browser or multilingual plugin.

11. How to add automatically new subscribers from other forms (e.g. Contact Form 7, WooCommerce checkout)

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.

Contact Form 7

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 ) {
	$submission = WPCF7_Submission::get_instance();
	$data = $submission->get_posted_data();
 
	$fields['email'] = $data["your-email"];
	$fields['name'] = trim( $data["your-name"]. " ". $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' );

There is also a code sample (gist.github.com/jeffmcneill/e7a53e11979ceddf81ec6c4764057c76) if you need to add the mailing lists inside a Contact Form 7 form and assign subscribers to lists on form submit.

WooCommerce checkout

With the following code you can add subscribers on checkout of WooCommerce plugin.
When the guest submits the checkout form and all fields are valid, a new subsciber with the submitted name and email will be added.

// Add the checkbox field
add_filter( 'woocommerce_checkout_fields' , function ( $fields ) {
	$fields['billing']['newsletter_subscription']	= array(
		'type' => 'checkbox',
		'class' => array('newsletter-checkbox'),
		'label' =>__("Yes, I would like to receive the Newsletter", "alo-easymail"),
		'clear' => true,
	);
	return $fields;
} );
 
// Subscribe if checkbox is checked
add_action( 'woocommerce_after_checkout_validation', function ( $posted ) {
	if ( ! empty ( $posted['newsletter_subscription'] ) ) {
		$fields['email'] = $posted["billing_email"];
		$fields['name'] = trim( $posted["billing_first_name"]. " ". $posted["billing_last_name"] );
		if ( function_exists ('alo_em_add_subscriber') && is_email( $fields['email'] ) )
		{
			alo_em_add_subscriber( $fields, 1, alo_em_get_language(true) );
		}
	}
});