Unsubscribe links in notification emails

UPDATE: Unsubscribe links have been implemented as a feature and are available now in version 10.7 of Subscribe2 HTML.

---

TL;DR – I’m thinking of adding a feature allowing unsubscription links in the notification email in the next version. I hope I’ve found a good implementation for this feature as it isn’t straightforward. What do you think? Comments please… 😉

---

For a long time the Roadmap for Subscribe2 has stated that unsubscribe links in the notification emails has been considered and dismissed as a development route.

Why? Well, for a few reasons:

• Subscribe2 is designed to be able to send individual emails but it can also be configured to send a single email to multiple recipients via the email BCC header – so the unsubscribe link would not be individual to each recipient
• Subscribe2 can send up to 4 email types and in 2 formats, HTML and plain text – formatting can get messy when trying to implement a solution for all email types
• Subscribe2 supports two user type, Registered and Public – the latter can click on a link to delete their email address but Registered Subscribers need to log in to their profile and change their setting – so a single link isn’t enough

So, where are we at right now?

Well, I think I have a satisfactory and workable solution now that I can spend more time developing Subscribe2 HTML while Subscribe2 is looked after by the folks at ReadyGraph. (See here for more about that split).

Basically, I have implemented a new {KEYWORD} called {UNSUBLINK}. This keyword is replaced by an unsubscribe link for Public Subscribers and a link to the ‘Your Subscriptions’ admin page for Registered Subscribers. These links are very basic in their implementation to allow for the plain text emails.

So, to allow greater control over the final output in the email there are also API filters for both links that passes both the generated link and the email type. This allows individual sites to use a little code to add some text and formatting to the link depending on the link and the email type. So for example (see below) you can return a nice sentence to Registered Subscribers with a word linked to the ‘Your Subscriptions’ page.

function custom_public_unsublink( $link, $email_type ) {
	if ( 'text' === $email_type ) {
		return "To unsubscribe click here:\r\n" . $link;
	} else {
		return 'To unsubscribe click here:
<a href="' . $link . '">' . $link . '</a>';
	}
}
add_filter( 's2_unsublink_public', 'custom_public_unsublink', 10, 2 );

function custom_registered_unsublink( $link, $email_type ) {
	if ( 'text' === $email_type ) {
		return "You may manage your subscription options from your profile\r\n" . $link;
	} else {
		return sprintf( 'You may manage your subscription options from your <a href="%s">profile</a>', $link );
	}
}
add_filter( 's2_unsublink_registered', 'custom_registered_unsublink', 10, 2 );

Finally then, this is the best solution I can currently think of, but I’m happy to hear some feedback on this before I push this feature out. Comments are open so let’s have some constructive feedback please. [Off topic comments will be deleted!]

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

Filtering the opt-out Authors

Version 7.0 of Subscribe2 introduced a new feature where Registered Subscribers could opt-out of receiving notifications from specific authors on multi-author sites.

Version 8.0 has improved on this a little by allowing site administrators to use a filter to trim down the list so unused author accounts can be removed from the list. To do this you simply code a small plugin extension something like this:

// 's2_authors' is the names of the new filter
add_filter('s2_authors', 'remove_author');
function remove_author($authors) {
	// our function takes an array of author objects as the input
	// you can then cycle through the array and remove any that you like on either 'ID' or 'display_name'
	$i = 0;
	foreach ( $authors as $author ) {
		// example use an if statement to check if author ID should be removed compared to a known ID
		if ( $author->ID == 1 ) {
			unset($authors[$i]);
		}
		$i++;
	}
	return $authors;
}

Themed User Subscriptions

One of the things I get asked about reasonably frequently is theming the “Your Subscriptions” page for end users.

If someone registers with your blog they can get additional control over their subscription by selecting which categories on your site they want notifications for and also the format of the email notification. It seems that some of you are not happy that this requires access to the WordPress administration menu area and you want to deploy the subscriptions form on the front of your site.

Well, there is good news. A developer has picked up on this request and is offering an extension for Subscribe2 that delivers exactly this functionality. And all they are asking for it is $5!

If this is something you want, go grab it here.

Subscribe2 and Custom Taxonomy Types

Subscribe2 was recently extended to allow notifications to be sent for Custom Post Types.

This introduction of code also highlighted the ability in WordPress to create Custom Taxonomy Types. Again, this is something done by developers and bloggers with a knowledge of PHP code.

Subscribe2 has now been extended again to allow the addition of custom taxonomies into the ‘categories’ that are used in WordPress by default. To add a custom taxonomy you have already created you need to added the following code into a custom plugin or to the function.php file in your theme.

function my_taxonomy_types($taxonomies) {
	// where 'my_taxonomy_type' is the name of your custom taxonomy
	$taxonomies[] = 'my_taxonomy_type';
	return $taxonomies;
}
add_filter('s2_taxonomies', 'my_taxonomy_types');

Subscribe2 and Custom Post Types

One of the new features introduced with WordPress 3.0 is custom post types. These are defined using code by developers and bloggers with a knowledge of PHP to allow WordPress to be extended to more of a CMS solution.

Subscribe2 can be enabled to send notifications for your custom post types by use of a filter. The code below give an example of how to register your custom post type with Subscribe2 so that these articles generate an email notification. I’d suggest you add this code to the plugin you are using to create your custom post type.

function my_post_types($types) {
	$types[] = 'my_post_type';
	return $types;
}

add_filter('s2_post_types', 'my_post_types');

Admin gets several emails

As previously covered in the FAQ section there are different subscriber types and different email preferences.

Each different email type is normally sent to admin with subscribers emails entered into the BCC Header (blind closed copy). This means your subscriber have the privacy of their email address maintained.

There are a maximum of four different emails types:

• Plain Text – Excerpt
• Plain Text – Full Post
• HTML – Excerpt
• HTML – Full Post

Emails are not sent if there are no subscribers but if there are subscribers admin will get a copy of the email.

Additionally, if you are on a host that restricts BCC: header length you can set the ‘number of recipients per email’ in the Settings area so that emails are constructed with size limited BCC: headers. This means your users will get the notification with the drawback being admin will get more emails.

If the number of recipients per email is set to 1 then emails are sent directly to individual addresses. Admin may not get emails in this case (if that address is not subscribed) and the emails may take longer to generate and send.

Future Posts / Daily Digests don’t work

Future Posts and Daily Digest emails both rely on another plugin to function.

Both features set a future event in order to complete the task and this future event is defined as part of WP-Cron, an excellent plugin written by Skippy.

If you don’t have WP-Cron activated on your WordPress installation these features will not work (despite being available).

Emails aren’t being sent

This is far too common a problem and in my experience is almost 100% down to server settings (apart from the one time I coded a bug into the email headers!).

SPAM is your enemy here. Many blog hosts are blocking or placing restrictions on the email sending capabilities of their servers (and rightly so!).

Subscribe2 sends emails to admin and puts subscribers email addresses into the Bcc: header space. Bcc: is used so that individual subscribers email addresses remain private to everyone except the blog admin.

If emails are “not arriving” check the following first:

• Do other emails from your site arrive (e.g. WordPress registrations) – if not check if you host is allowing email sending, check you aren’t using an “off domain” email address as the sender
• Are some users getting the emails and others not – check with your host for restriction relating to emails and get users to check their SPAM folders
• Do regular publication emails arrive but future posts and digest emails don’t – you need WP-Cron for future posts and daily digest functionality

In summary lots of people use this plugin every day without problems – the issue is most likely with your set up or host.

However, there is some work-around functionality built into the plugin to cope with hosts who cap the number of recipients per email. There is a setting in the plugin specified as follows:

define('DREAMHOST', false);

(The reason the setting is called DREAMHOST is because this is the name of a hosting provider that caps the number of recipients per email!)

Anyway, set this to true in order to limit the number of recipients per email to 30. This may solve “No email” problems due to host email restrictions.

HTML email

Subscribe2 allows Registered Users the option to receive emails in HTML format. Public Subscribers will only receive plain text emails containing an excerpt of the post.

The additional options given to registered users are intended to provide an incentive to sign up to the blog.

HTML emails are not officially supported for non-registered users. If you want this functionality please feel free to amend the code yourself or you can purchase amended code.

The off-the-peg HTML solution at a cost of $40US payable via PayPal is available via the WPPlugin store. The update code:

– Sends HTML emails sent to all confirmed public subscribers
– Has the ability to send HTML emails from Post->Mail Subscribers
– Sends Digest Emails containing HTML