Troubleshooting emails in Subscribe2

Over 6 years ago I briefly wrote about trouble shooting failed emails in Subscribe2. And 6 years later I still get this same issued raised time after time.

So, I thought it would be good to write a step by step guide to how you might go about testing and trouble shooting.

So, to start with some assumptions. I’m presuming you are using WordPress and Subscribe2 and you are using current release versions. I’m also presuming that you have followed the installation instructions for Subscribe2 and that you do successfully get some emails from your blog, for things like registrations and comments (if you aren’t getting these either then you have a wider failure in sending emails and you need to call your hosting provider).

Now we can work on some steps to try to get things working:

  1. Firstly, visit the Subscribe2->Settings page in the WordPress administration area. If you see any error messages in the red box over the top of the screen you need to get those fixed.
  2. Have you checked for conflicting plugins and themes? Check the list of known conflicts and if that doesn’t help then disable all plugins except Subscribe2 and revert to a core WordPress theme (like TwentyTwelve or TwentyThirteen). Test again and see if Subscribe2 works. If it does then you have a conflict somewhere, re-enable your theme and then plugins one at a time testing after each and every step to find the conflict. It would help greatly if you could let me know about conflicts too so the list can be kept up to date.
  3. In Subscribe2->Settings change the drop down selector where it says “Send Email From:” to a user account name and choose an account with an email address that end with your blogs URL. For example, if your blog address is http://www.my-blog.com the account should have an email address like admin@my-blog.com. Subscribe2 will display a warning message if the account has a different email address. After making the change test everything again.
  4. Next step, are you using Subscribe2 in per-post or digest mode?

Digest Mode
Digest mode sends a summary of posts made in a time period. The periodicity interval can be set by you but the event is triggered in the WordPress cron system.

  1. You need to check that the WordPress cron system is working. Install WP-Crontrol on your site and then visit Tools->Crontrol. Look at the “Next Run” times for events and in particular the subscribe2_cron event. If these are in the past then cron isn’t working. You might want to try adding define( 'ALTERNATE_WP_CRON', true ); to your wp-config.php file and see of that resolves the issue

Per-post Mode
Per-post mode sends posts at the time they are published (both live and scheduled). There are a few things that need checking and some of these apply to Digest mode too.

  1. In the Subscribe2->Settings page under the Email Settings tab make sure you have set the number of recipients per email to 1 (This is the default). Setting it higher than 1 sends a single email to groups of individuals and while this is a little more efficient it also looks a lot more like spam and is more likely to be blocked or filtered by anti-spam measures.
  2. In the Subscribe2->Settings page under the Registered Users tab make sure that you have not excluded any categories
  3. In the Subscribe2->Settings page under the Templates tab make sure that your templates are not empty
  4. Install an email logging plugin and then try sending a test email from the Suscribe2->Send Email page. Do the emails show in the log? Check the log again when you make a new post. If the emails are being logged then Subscribe2 and WordPress are generating the email and it is being blocked on the server, time to move to the next step.
  5. Speak with your hosting provider. Be patient with them. Ask them what restrictions or limitations they have in place on the sending of emails via the PHP mail() function. If they tell you it is not restricted ask them to check again, ALL hosting providers limit this function somehow otherwise they would be a spammer haven. Ask them exactly how the limit is applied and work with them to ensure your site remains within the restrictions. You may need an email queuing solution

Subscribe2 – the next version

As I’m sure you know, WordPress 3.1 is now available on general release. This new version has made a couple of changes that are affecting Subscribe2.

Firstly, in version 3.0 of WordPress the usermeta() functions were all deprecated and replaced with user_meta() equivalents (so update_usermeta() is now update_user_meta()). The other change is that these functions now return an array rather than a string by default.

Strangely, in WordPress 3.0 this didn’t seem to be a problem but some users are seeing errors in WordPress 3.1.

Secondly, WordPress 3.1 replaced the WP_User_Search class with WP_User_Query. Now, I can’t find any documentation about this new class which is of course a great help when writing a plugin! (If you can find any please let me know!)

Again, this seems not to be affecting all users who are on WordPress 3.1 but it would be sensible to drop use of a deprecated class.

Subscribe2 currently requires at least WordPress 2.8. But I’m wondering how many people I’m leaving behind if I make the minimum requirement 3.0. So, please use the poll below and tell me what version of WordPress you are currently using on you main blog.

WordPress 2.9 compatibility

Since the release of WordPress 2.9 about a week ago I’ve been doing some testing looking for issues. Subscribe2 appears to work pretty well with WordPress 2.9 but there are some issues with the cron periodic email events on some servers with WordPress 2.9. This is not an issue in Subscribe2 but a bug in the WordPress code.

I found more details and a fix here as well as details of some other problems.

The bug in Susbcribe2 will be apparent if, and only if:

  • You are using Subscribe2 on WordPress 2.9
  • You have set Subscribe2 to email notifications periodically on a digest basis rather than per-post
  • Your server configuration makes your site prone to the WordPress 2.9 bug

You can try the following fixes:

  • Apply the files link at the site above
  • Replace wp-includes/http.php with the version in the WordPress trunk code
  • Wait for WordPress 2.9.1
  • Add define('ALTERNATE_WP_CRON', true); to your wp-config.php file

I compared the files in the first and second options and they look identical to me but you may trust files direct from WordPress more.

Guides and Stats

The new support forum appears to be working and I think (so far) it is saving me time – time will tell if this trend continues. But something that may help further is a comprehensive guide to Subscribe2 produced independently by the iAssistant.

The guide is 40+ pages long and it provides an in depth set of instructions and descriptions of Subscribe2 features. I have had a very small part in the production of this guide (mainly pointing out additional areas of functionality and clarifying how some things work). It has been written in an easily understood manner that the novice will comprehend. I hope you will consider using this guide if you are struggling to start using Subscribe2.

CoverPage

And since the release of version 5.1 has bumped the download counter past the 200,000 mark and there have now been more than half a million visits to this site I guess there are quite a few of you who will find this guide worth every penny!

Support for Subscribe2

Many users of Subscribe2 post comments commending the outstanding support that is offered on the plugin and ruing the fact that this does not happen more. The sad fact is that a great number of the comments posted are either issues that have already been discussed many times over and the answers are already available, or they are requests for custom changes from the default plugin for an individuals benefit.

Recently, the folks at WordPress have reviewed their software licence and introduced Commercially Supported Themes on the main WordPress.org site. They have also introduced enterprise-level support for large-scale users of WordPress.

So, that leaves me wondering how to handle the continued support of Subscribe2. You see, much as though I think I should support my plugin and help people to use it as best they can I am often left bewildered that it seems to be overlooked that both the plugin and the support are currently FREE. And yet the level of functionality and support seem to be more consistent with that of software that has been bought!

Perhaps I should start acting more like other plugin authors and provide little to no support. Maybe I should direct everyone to the ReadMe and FAQ section of the website. Perhaps I should start charging for my assistance.

I really don’t know for sure what will happen next. I think I have decided already to start directing queries to the FAQ and ReadMe more however when I’ve done this in the past it really doesn’t save me any time – I still have to make the comment and I still usually get a follow up reply.

So, what would you do if you were me?

Error Messages

Subscribe2 attempts to check that emails have been successfully sent by reporting the callback returned by the WordPress wp_mail() function.

In your server or WordPress install are not correctly configured this can result in error message despite successful sending of emails.

To overcome these issues access the PHPMailer files directly, locate a language error file and uploaded to your WordPress site (wp-content/languages/ for example).

Next, get yourself a Mailer plugin like the one suggested here and put the following line in the code.

$phpmailer->setLanguage( 'en', '../wp-content/languages/' );

This will ensure that you don’t get:

Language string failed to load: instantiate

Mail Debug

Ben Forchhammer has just released a new plugin called Mail Debug.

This plugin could be of great assistance in finding out why emails are not being sent when using Subscribe2. The documentation states:

This plugin when activated automatically redirects all email sent through wp_mail/phpmailer to the user currently logged in.

The redirected email contains information about where the original email would have been sent to.

Use this plugin if you want to test email-sending features without actually sending emails our to anyone but yourself. I wrote this plugin to ease debugging with subscribe2.

So, if you are having problems with Subscribe2 then give this plugin a try.

SMTP Mailer

By far the majority of requests for help are still something to do with emails – mainly not sending! This is normally down to server restrictions that are based on limitations to recipients per email or time based choking.

One potential way around this might be to channel your emails via an SMTP server so the plugin below might be worth a try. Amend the plugin code below with your smtp server, your usewrname and password. Upload it and activate it then try sending your notifications. If it works send some kudos (or hard cash) my way! :D

<?php
/*
Plugin Name: SMTP Mailer
Plugin URI: http://subscribe2.wordpress.com
Description: Allows wp_mail() to send via SMTP server.
Version: 1.0
Author: Matthew Robinson
Author URI: http://subscribe2.wordpress.com
*/

/*
Copyright (C) 2006-8 Matthew Robinson

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

http://www.gnu.org/licenses/gpl.html

*/

/*
Instructions
1/ Change 'smtp.domain.com' to the server name of you out-going email server
2/ Change 'my_username' to your email mailbox username
3/ Change 'my_password' to your email mailbaox password
4/ Save this file and upload it to wp-content/plugins, then activate the plugin as normal
5/ Test is works by emailing a notification via Write->Subscribers in the Subscribe2 plugin
*/

add_action('phpmailer_init', 'wp_mail_to_smtp');

function wp_mail_to_smtp(&$phpmailer) {
	$phpmailer->Mailer = 'smtp';
	$phpmailer->SMTPAuth = true;
	$phpmailer->Host = 'smtp.domain.com';
	$phpmailer->Port = '25';
	$phpmailer->Username = 'my_username';
	$phpmailer->Password = 'my_password';
}
?>

Known Issues and Fixes

There are currently two known issues with Subscribe2 and it’s features that are being caused by the core WordPress files. If you feel comfortable editing PHP code here are the fixes:

Issue 1: Upon activating the plugin you may get an error regarding openbase_dir

Issue 1 has been fixed by an update to the WordPress core files.

To resolve this issue locate the file install-helper.php in wp-admin. On line 2 you’ll find the following
require_once ('../wp-config.php');

Change this to:
require_once (dirname(dirname(__FILE__)).'/wp-config.php');

Issue 2: When a Subscriber confirms a subscribption the webpage shown will replace the names of all your pages with “Subscription Confirmed”

Issue 2 has been fixed by an update to Subscribe2.

To resolve this issue you have two options:

Option 1: Comment out line 2183 in Subscribe2.php.

Change it from:
add_filter('the_title', array(&$this, 'title_filter'));

To:
//add_filter('the_title', array(&$this, 'title_filter'));

Option 2: Locate classes.php in wp-includes and edit line 521.

Change it from:
$output .= $indent . '<li class="' . $css_class . '"><a>ID) . '" title="' . attribute_escape(apply_filters('the_title', $page->post_title)) . '">' . apply_filters('the_title', $page->post_title) . '</a>';

To:
$output .= $indent . '<li class="' . $css_class . '"><a>ID) . '" title="' . attribute_escape($page->post_title) . '">' . $page->post_title . '</a>';

Testing Mail

By far the majority of requests for help are something to do with emails – either not sending or sending duplicates. With this in mind I have posted a Test Mail plugin in comments but WordPress.com replaces quotes with smartquotes resulting in errors when you try to copy and paste into a file.

So, try the following. This test plugin should result in an email being sent to the address you define on line 12 each time your website is loaded. So, don’t leave the plugin activated for long or you’ll fill your inbox!

You can copy and paste the code or download this file and rename it as a *.php file.

<?php
/*
Plugin Name: Mail Test
Description: PHP Mail Function Tester
Author: Matthew Robinson.
Version: 1.0
Author URI: http://subscribe2.wordpress.com
*/

function mail_test() {
//Define the following as your email address
$myemail = 'email@email.com';
// Leave the following alone
$subject = 'WordPress Email Test';
$mailtext = 'This email was sent from your WordPress blog by the Mail Test Plugin - your emails are working for simple mail';
$headers .= "MIME-Version: 1.0\n";
$headers .= "Content-Type: text/plain; charset=\"". get_bloginfo('charset') . "\"\n";
$headers .= "From: " . $myemail . "\n";
$headers .= "Return-Path: " . $myemail . "\n";
$headers .= "Reply-To: " . $myemail . "\n";
$headers .= "X-Mailer:PHP" . phpversion() . "\n";
$headers .= "Precedence: list\nList-Id: " . get_option('blogname') . "\n";
@mail($myemail, $subject, $mailtext, $headers);
}

// Run our code after the plugins have loaded.
add_action('plugins_loaded', 'mail_test');
?>