bbPress Notify (No-Spam) Documentation

The bbPress Notify (No-Spam) is a free plugin that lets you control who gets notifications of new Topics and Replies in your bbPress Forum, what they look like, and also serves as the base for a LOT more functionality via the premium add-ons.

If you don’t have your copy yet, you can get it here.

Oh, and because the plugin has such a huge name, we call it by its nickname instead: bbpnns.

Full disclosure: This page contains at least one affiliate link to services that we endorse.

Installation
Configuration
Extending bbpnns
F.A.Q.

Installation

bbpnns can be installed exactly like any other WordPress plugin.

Via the Admin:

Go to Admin > Plugins > Add New;
Type bbpress-notify-nospam in the search field;
Click Install in the plugin’s card;
Click Activate;

Via FTP:

Download the Zip file from WordPress.org;
Unzip it in your local computer;
Upload the unzipped directory into your wp-content/plugins/ directory;
Go to Admin > Plugins;
Click Activate in the uploaded plugin;

Configuration

Once you’ve installed and activated bbpnns, you’ll find the settings near the bottom of your Admin sidebar.

Click the Settings link or the bbPress Notify (No-Spam) link to open the plugin settings.

The General Tab

The first tab to appear is the General tab, containing the Global Settings.

The settings are:

Email Type
Background Notifications
Subject Line Encoding

Email Type

Define whether you want to send HTML messages, Plain Text Messages, or Both. We strongly recommend selecting Both, as it will create one message with two MIME types – one being the HTML and one being the Plain Text message. That way users who prefer to receive Plain Text messages (yes, they exist; we know a few!) will be able to see the notifications in their preferred format.

Background Notifications

This setting will tell bbpnns to not try to send out notifications the moment that a new Topic or Reply is created. Turning this OFF will potentially cause lots of problems in a production environment.

The reason being that if there are many users being notified, your web host may kill the process before the end of the mailouts. If that happens, not only will some people not receive their notifications, but the person who created the Topic/Reply will receive a 503 Timeout message. They’ll think that their message did not get created, and will try creating it again. You’ll end up with a very frustrated visitor, several copies of the same Topic/Reply, and lots of people flagging your messages as spam.

When you turn on background notifications, bbpnns will create a wp-cron job which will be kicked off the next time the site is visited (because that’s how WP Cron works). This process will run in the background, without affecting your visitors’ browsing experience.

Now, if you don’t have much traffic on your site, it could take a very long time for the notification job to be triggered. There’s a workaround for this: use a Real Cron Job, or a Cron service.

SiteGround has a great tutorial explaining how to set up a real cron job for WordPress for cPanel users.

If you want your cron job running at shorter intervals than what your host allows, you can sign up for a free cron-job.org account or some equivalent service.

In summary, keep the setting OFF when in a development/staging environment and you need to check immediate notifications. Turn it ON in production for better performance.

Subject Line Encoding

Enable this option if you see HTML entities in your subject line. Most common is to see ‐ due to how WordPress encodes the post titles. The down side is that if you have email logging plugins such as WP Email Logging, you’ll see lots of gibberish in the subject line field of the logs. But hey, you want your participants to be happy, right?

Topics Settings

This is where you’ll control everything related to new topics.

Recipients

The Recipients setting contains a drop-down of all the available roles in your WordPress installation. You can choose to leave this blank, as whatever role you choose will force notifications to all users of that given role. Even if they won’t want it.

Historically speaking, this plugin was created to notify administrators of new messages, as long as they were not flagged as spam. Over time, users requested that we allow other roles to be included in the notification, and this is the result.

Be careful, however, not to trigger the wrath of role members who do not want to be notified (or spammed, in their point of view) when turning this on. You might even want to consider installing the Opt Out Add-on to let people unsubscribe.

Admin UI Topic Notifications

This controls the default state of the checkbox in the Admin > Topics > Add New/Edit Topic > Send Notifications metabox.

The Send Notifications checkbox is handy if you have the habit of creating topics via the Admin instead of the Front End.

Pro Tip: It’s even more handy when you’re troubleshooting the mailouts and don’t want to waste time creating new topics for each test. Just go to an existing topic, make sure the checkbox is checked and click Update to trigger a whole new mailout to all recipients.

bbPress Forums Subscriptions Override

Enable this setting to stop bbPress from sending the default notification message. You can also choose to leave the Recipient Roles field empty and turn this on. That way only users who have subscribed to the forum will receive notifications of new Topics in that given forum.

You can also mix and match. For example, select Administrators in the Roles field and enable overrides to always tell Admins of new topics, yet only tell non-admin subscribers to that forum.

This also works as a pre-requisite for two other available features:

Automatically subscribe new users to all forums

This setting makes it so that every new user created gets automatically subscribed to all published forums. The end result is that the users get notifications of all new topics. They can unsubscribe via the bbPress Unsubscribe links at any time.

Automatically subscribe all forum subscribers to newly created topics

This one has the consequence of making forum subscribers also receive notifications of new replies, not only new topics. They can unsubscribe via the bbPress Unsubscribe links at any time.

Notify Authors of Their Own Topics

The setting says it all. Some people complain that they don’t want to receive an email as they know they created a topic. Others feel nobody got alerted to their new post if they didn’t. Your mileage will vary. Note that this is a global setting, and nobody has ever asked that we make it a per-user setting.

Force Admin-only emails if Forum is Hidden

Again, pretty self explanatory. We’re not sure if this was ever used, but we need to keep it for backwards compatibility.

Topic E-mail Subject Line

This is where things get interesting. bbpnns supports a series of pre-defined tags in both the Email Subject and body. Depending on your installed Add-Ons, you’ll see even more tags. The base tags are:

[blogname] – The blog name field set in Settings > General;
[recipient-first_name] – The recipients First Name as set in their Profile;
[recipient-last_name] – The recipients Last Name as set in their Profile;
[recipient-display_name] – The Display Name set in the recipients Profile;
[recipient-user_nicename] – The user’s Nickname field;
[topic-title] – The title of the topic;
[topic-content] – The content of the topic;
[topic-excerpt] – The Topic excerpt. Note that this usually does not have any formatting;
[topic-url] – The URL of the topic (without reply form). Note that this is *just* the URL, not the whole link. Use it as the href value of the link;
[topic-replyurl] – The URL that shows the topic with the reply form;
[topic-author] – The name of the topic author;
[topic-author-email] – The author’s email address;
[topic-forum] – The name of the forum in which the topic was created;
[date] – The date. You can control the format of the date by setting the ‘format’ attribute. E.g. [date format=”Y-m-d H:i:s”]. See the PHP date function for more information on the supported format. Not passing the format attribute will default to the date/time format you specified in Admin > Settings > General.

Topic E-mail Body

This is the meat of your notification. It will be taken as-is and sent via email. It supports the same base tags as the Subject line.

Once you’ve completed your topics settings, SAVE and go the Replies tab.

Replies Settings

The Replies settings screen is almost an exact replica of the Topics screen.

There are only 3 differences:

It applies to Replies instead of Topics :-);
You can force notifications to forums subscribers (the extra setting in the Subscriptions Override section); The difference between this one and the Topics one is that this one doesn’t actually subscribe anyone.
A much larger set of tags.

The Tags

The supported tags are:

[blogname] – The blog name field set in Settings > General;
[recipient-first_name] – The recipients First Name as set in their Profile;
[recipient-last_name] – The recipients Last Name as set in their Profile;
[recipient-display_name] – The Display Name set in the recipients Profile;
[recipient-user_nicename] – The user’s Nickname field;
[reply-title] – The title of the reply;
[reply-content] – The content of the reply;
[reply-excerpt] – The Reply excerpt. Note that this usually does not have any formatting;
[reply-url] – The URL of the reply (without reply form). Note that this is *just* the URL, not the whole link. Use it as the href value of the link;
[reply-replyurl] – The URL that shows the reply with the reply form;
[reply-author] – The name of the reply author;
[reply-author-email] – The reply author’s email address;
[reply-forum] – The name of the forum in which the reply was created;
[topic-url] – The URL of the topic (without reply form). Note that this is *just* the URL, not the whole link. Use it as the href value of the link;
[topic-title] – The title of the topic;
[topic-author] – The name of the topic author;
[topic-author-email] – The author’s email address;
[topic-content] – The content of the topic;
[topic-excerpt] – The Topic excerpt. Note that this usually does not have any formatting;
[date] – The date. You can control the format of the date by setting the ‘format’ attribute. E.g. [date format=”Y-m-d H:i:s”]. See the PHP date function for more information on the supported format. Not passing the format attribute will default to the date/time format you specified in Admin > Settings > General.

The Support Tab

The Support tab has 2 sections:

Support Information
The Dry-run Tool

Support Information

This field contains important data that will help us help you figure out problems. Please provide it with your support requests. Due to the possibly sensitive nature of the data, do not paste it in the support forums. You’ll find instructions on how to safely send it to us.

The Dry-run Tool

This is an super duper handy tool to understand who would get notified when a new topic or reply is created. Select the type of notification (topic or reply) and start typing in the field below to select an existing topic/reply. This will mimic a mailout but not send any messages. You will be informed of who got included in the recipients list, who got dropped, and why/by which rule or add-on.

Extending bbpnns

bbpnns comes with around several filters that make it extremely customizable. We also offer several premium add-ons which make the plugin even more powerful.

The filters

bbpnns_core_subscribers
bbpnns_dry_run
bbpnns_extra_headers
bbpnns_extra_headers_recipient
bbpnns_extra_reply_tags
bbpnns_extra_topic_tags
bbpnns_filter_email_body_for_user
bbpnns_filter_email_body_in_build
bbpnns_filter_email_subject_for_user
bbpnns_filter_email_subject_in_build
bbpnns_filter_recipients_before_send
bbpnns_handle_mandrill_nl2br
bbpnns_notify_authors_reply
bbpnns_notify_authors_topic
bbpnns_post_status_blacklist
bbpnns_post_status_whitelist
bbpnns_reply_url
bbpnns_skip_notification
bbpnns_skip_reply_notification
bbpnns_skip_topic_notification
bbpnns_subject_enc_preferences
bbpnns_topic_reply
bbpnns_topic_url
bbpress_notify_recipients_hidden_forum
bbpress_reply_notify_recipients
bbpress_topic_notify_recipients
bpnns_excerpt_size

Add-Ons

Click the Admin > bbPress Notify (No-Spam) > Add-ons link to see all of our available add-ons. From Digests to Replies by Email, to Bulk Mailing, we probably have something you need. And if we don’t, do reach out and we’ll discuss a solution for your requirements.

F.A.Q.

How do I fix timeouts even with background notifications enabled?

Some hosts are extra stingy when it comes to CPU time. If you have a huge recipient list and find that some users are not getting notified, the best solution is to get the Bulk Mailer add-on. It uses Mailgun or SendGrid APIs to send one message for every batch of 1000 recipients in the same time it would take to notify a single user.

Does the bbpnns send Digests?

No, but there’s an Add-on for that :-).

How do I change the From Name/Address?

bbpnns uses your Admin > Settings > General > Admin Email field by default. If that’s not good enough for you, you can hook into the bbpnns_extra_headers filter to replace the From: header entry.

How do I add support for a custom tag?

You can support custom tags by adding some code to your functions.php file.

If you don’t need any recipient-specific information, hook into bbpnns_filter_email_subject_in_build to modify the email subject line and bbpnns_filter_email_body_in_build to modify the body. They take 3 parameters:

$content: The subject line or email body that is to be changed.
$type: Whether the post is a topic or reply.
$post_id: The ID of the topic/reply being notified.

You can then modify and return the $content to handle any special tags you want.

UseStrict Consulting