Mostly WordPress plus some other random thoughts and musings …

Email-Users Debugging – why don’t my users receive email?

Periodically users post questions in the Email-Users support forum wondering why their users don’t receive email messages when they expect them to. There are many reasons why users don’t receive email, some are within the control of Email-Users but many are not.

Email-Users User Settings

Email-Users is based on two user settings (which appear on the user’s profile page):

Receive post or page notification emails

Receive emails sent to multiple recipients

Email-Users has a plugin level setting which allows end users to modify their own settings which is enabled by default. When it is disabled, only users with the proper permissions can modify user settings related to Email-Users. No matter how the user has their settings configured, a user can always receive an email when they are the only recipient.

In Email-Users v4.5.2 a new Dashboard Widget has been added which reports the number of users who have their settings configured to receive each type of email. This information also appears on the Plugin Settings Page and should either of the types of email not have any users set to receive email, a warning message is displayed at the top of the screen.

Changing the Email-Users settings for a large number of users can be accomplished from the User Setting menu. By selecting the desired Users, Notifications and Mass Email can be enabled or disabled for a large number of users at one time. For a site that has a large number of users, the number of users which appear on each page can be changed on the Settings Page.

Test Email

Before sending out notifications or messages, it is important to validate the underlying WordPress email system is working. On the Plugin Settings page there is the ability to send a Test Message.

Email-Users utilizes WordPress’ wp_mail() function to send email. It does not interact with the OS or PHP mail functions directly. By using wp_mail(), which can be overridden by other WordPress plugins, Email-Users can work with different server configurations and email infrastructure.

If you don’t receive the test message then you may have a problem with your underlying WordPress email system. Do you receive email for user registration and comments? If not, there is something wrong which is out of the scope of Email-Users.

On some servers plugins such as WP-Mail-SMTP (this is just an example, there are others) can be used in situations where email is being sent but isn’t being received.

There is no point in trying to send Notifications or Mass Emails if the Test Message isn’t working.

BCC Limits

Some servers limit the number of email addresses which can appear in the BCC header of an email message. Email-Users has a setting to control the number of addresses which appear in the BCC field. If Email-Users is working for a small number of users but isn’t working for a larger number (e.g. all of your users) , you may be dealing with a BCC limit.

If you are able to send email to 3-5 users by selecting them from the list of users, I would next try sending a message to about 10 users and see if that works.

The sending logic is only different when 1 user is selected. Anytime more than one user is selected (2, 10, 37, 67, 1000, etc.), the same logic path through the code is used.

The only thing that is different is how many emails are sent and that is based on the BCC limit setting. If there is no limit, which is the default, it sends one email with all recipients on the BCC line. For any other setting, it will send some number of emails, depending on the BCC limit. If the BCC limit was set to 30 and you had 67 recipients, it would send 3 emails: The first 30, the second 30, and the final 7.

Advanced Debugging

In some situations you may want to examine what Email-Users is doing in gory detail. For development purposes Email-Users has a DEBUG mode. When in debug mode Email-Users will log quite a bit of information to the PHP error console using error_log() including the actual email headers it generates. It can be very useful to see the actual mail headers to ensure the expected recipients are actually included.

Because gaining access to the contents of the error_log() differs from web host to web host, I recommend using a WordPress debugging capability to capture it in the site’s /wp-content folder. By setting WP_DEBUG_LOG to true in your wp-config.php file, you can easily access the resulting debug.log file. On my development machine I use the following set up in my wp-config.php file:

You would not want this on a production server but to temporarily chase down a problem, it works well. Unfortunately some plugins issue a lot of notices or warnings so you can run into the “Headers already sent” problem so you may want to tweak the above settings to meet your needs.

Once your WordPress debugging settings are tuned to your liking, you need to enable Debug for Email-Users. Doing this requires manually editing one of the plugin files.

On or about line 46 of the email-users.php file you will find a line of code which reads:

define( ‘MAILUSERS_DEBUG’, false);

You need to change the code such that it reads:

define( ‘MAILUSERS_DEBUG’, true);

After you have made this change Email-Users will output information to the error_log.

In the image below you can see a series of email headers each with 10 email addresses in the BCC field (BCC limit is set to 10).

If the information in the error_log is what is expected then there is little, if anything which can be done from Email-Users. At this point you will need to figure out where the email is routing to and where it isn’t which is beyond the scope of the Email-Users plugin.

Anecdote

I was using Email-Users on our local Swim Team’s web site and heard from a number of parents that they weren’t receiving emails. I noticed that all of the reports were coming from families with RoadRunner email addresses. It turned out that Time Warner had blacklisted our Swim Team’s domain. By filling out a form with TWC and verifying some information, we were able to get white listed but for several weeks I wasn’t sure how to resolve it.