bbPress Notify (No-Spam) Reply by Email Documentation
bbpnns Reply By Email (RBE for short) is a powerful plugin. It gives your forum participants the ability to reply to new forum posts without having to log into your site. They can even dictate their emails on their phones, so no typing is required.
However, getting it set up initially can be a little tricky if you don’t understand the concept behind it. Keep reading if that felt close to home.
RBE is an extension of bbpnns. It relies on bbpnns to send the notifications to your users. When it sees a notification going out, it will change the reply-to email header of that outgoing message so that any replies go to a mailbox it has access to.
From time to time (more on that later) it will check that mailbox, parse the headers and body of each message and create the reply under the correct topic. It even respects nested replies!
By the end of this article you’ll:
- Know what a Plus Alias (or Dynamic Alias) is;
- Have a better understanding of what a Cron job and Webhook are;
- Have all you need to easily set up your Reply By Email add-on.
As you just read, RBE needs to have access to all of the email replies so it can do its thing. To do its thing, it needs to know a few pieces of information: who’s the user posting, and what’s the forum, topic, and parent reply (if any) it should take into consideration when posting the body of the message.
There aren’t many reliable ways for it to do that without putting a huge performance hit on the WordPress database. Enter Plus Aliases (aka Dynamic Aliases).
Plus Aliases (we’ll stick with that name for convenience) are a handy feature that Gmail and a few other email providers came up with. It allows one mailbox to act as pretty much infinite mailboxes. How? By using a simple character, the + sign, to identify the actual mailbox (before it) and any combination of characters (except @) after it and send all messages to the actual mailbox.
So let’s take the email address email@example.com as an example. There are 2 parts to it: foo, the account, and foobar.com the server. What Plus Alias support does is let you send a message to something like firstname.lastname@example.org and still get the message as if it was sent to email@example.com.
That’s really handy! Common applications for this are: reduce the number of mailboxes you need when applied in conjunction with mail rules; know which site is selling your email to spammers by using a special alias for each site you give your email to; and allow Reply By Email to know the meta data required to post a message.
So how do I get my hands on a Plus Alias, you ask?
So far there are 2 large email providers that support Plus Aliases: Gmail and Hotmail/Outlook. Oddly enough, Outlook 365 does not support them – not easily at least. The good news is that those that do are free.
You’ll find the Mailbox connection settings under
Admin > Settings > bbPress Notify (No-Spam) – Reply by Email Settings > General tab
Using Gmail/G Suite (Less Secure Apps)
This section covers the option to connect to Gmail/G Suite using username and password, with Less Secure Apps settings turned on. Note that Google will be shutting down Less Secure Apps starting June/2020. bbpnns Reply By Email will support oAuth connections in version 2.0, scheduled to be released by the end of May/2020. Google will give a grace period of about 1 year, but we strongly recommend that you switch to the oAuth connection as soon as it is made available.
Gmail and G Suite (formerly Google Apps) are the most popular Plus Alias providers out there. Heck, they may have been the original inventors of Plus Aliases.
RBE comes with pre-defined settings to connect to Gmail (and G Suite, but we’ll just say Gmail for brevity). All you need to do is paste the full email address in the username input field, the password in the password field and Bob’s your uncle. Well, most of the time. Gmail can get a bit picky with who accesses their mailboxes.
First, we recommend that you get a dedicated mailbox for RBE to use. If you choose to use your own or one that has, say 7GB of old messages going back 10 years, RBE will probably have a hard time finding the ones that it really cares about.
Second, you really need to test the connection after entering the Gmail credentials. If it fails you should log into the mailbox and look for security emails coming from Google.
You may have to do one or both of the following:
Follow the links above for information on how to enable them. Usually just enabling Less Secure Apps works fine. Click the Test Connection button after each one to see if it works. Don’t be discouraged with the ‘Less Secure’ terminology. RBE communicates with all mail servers via secure SSL connections.
WARNING: There’s one caveat regarding the Gmail account to use. If you’re using a gmail account in your Admin > Settings > General > Email Address, then you cannot use the same account for RBE. That’s because bbpnns uses that email address in the From field, and Gmail will see that the From and To fields are the same and ignore the Reply-to header containing the meta data that RBE needs. It’s a Gmail thing and we can’t do anything about it. Sorry.
Once it’s all set up, click Test Connection again and it should work just fine. Remember to save!
Gmail/G Suite (oAuth)
Connecting to a Gmail or G Suite account via oAuth will require a few extra steps, but it’s a one time thing, so don’t worry.
You will need to create a Google Cloud Project in order to grab the required Client ID and Client Secret. Here’s how you do that.
- Log in to Google Developer Console at https://console.developers.google.com using your google account credentials.
- If this is your first time logging in, you may need to accept the terms of service.
- Once you’re sent to the Dashboard, click the Library link on the left. We need to enable the Gmail API library.
- Enter Gmail in the “Search for APIs & Services” box.
- Click the Gmail API result.
- Click Enable.
- Click the Hamburger Icon on the left to go back to the Projects screen.
- Click the Select a Project link at the top of the screen.
- Click New Project on the modal that opens.
- Enter any project name or leave the one suggested for you, click Create. Note that if you’re using a Gmail account, you most likely will not have any organization to select. If you’re using G Suite, select your organization of Google complains about no Organization being selected. The same goes for Location.
- Before creating the credentials, you’ll need click the oAuth Consent screen link. Google likes to change things from time to time, so you may see the link in a couple of different places.
- When prompted to select Internal or External, click Internal and Create.
- On this next screen, enter bbpnns Reply By Email in the Application Name field, skip the application logo field, but make sure your email address is selected.
- Click Add Scope in the section below the email address.
- Select the Gmail API scope (https://mail.google.com). If you don’t see it right away, type Gmail in the search box and it should show up as the first selectable checkbox.
- Enter your site’s domain in the Authorized Domains field. Hit Enter after typing the domain name to add more.
- Now we get to create the credentials. Click Credentials link on the left menu.
- Click Create Credentials at the top of the page, and select oAuth Client ID.
- Click the Add URI button under Authorized Redirect URIs section.
- Enter the Redirect URI you were given in the Reply by Email settings screen.
- Click Create. You will be shown the Client ID and Secret in a modal. Copy them to a separate document.
And that’s (finally) it. Now you have the Client ID and Client Secret to use in the Reply by Email settings screen. Note that you have the option of pasting the data in their respective fields or adding them as constant values in wp-config.php.
Hotmail was my very first public email address. That’s when Geocities still existed and IE 3 would come in a set of 3 or more floppy disks (now known as the save icon). A few decades later Microsoft buys it and makes it part of the Outlook family.
The good part is that it also supports Plus Aliases, and even better, it doesn’t seem to complain about less secure apps or application passwords. Just paste the full email address in the username field, the password in the password field, and click Test Connection. Remember to Save!
Issues with Post SMTP Plugin
Post SMTP is a very handy plugin but unfortunately it’s been known to drop the reply-to header. This effectively breaks the Reply by Email add-on entirely as the reply-to header is its back-bone, so to speak.
From Email to Forums
Now that you’ve got your mailbox set up, it’s time to take RBE for a spin. The first thing you’ll need to do is to make sure bbpnns is working properly. Without it, RBE cannot set the headers that it needs to do its thing.
Setting up bbpnns is pretty trivial, if you’re working on a brand new wordpress install without any real users. Things get tricky if you have real users and don’t want to spam them with test notifications. We strongly recommend setting up a staging site to test out the settings, or you’ll run the risk of having some very angry users.
If you must test on a live site (please don’t!), then at least temporarily set the notification role to Administrator (or some custom role created just for testing) and disable Override Subscriptions to Forums and Override Subscriptions to Topics in the Topics and Replies tabs of bbpnns, respectively. Don’t forget to turn off background notifications during testing.
You may find it tedious to create new topics in the front-end for testing. We find it, too! And with that in mind we created the Send Notifications metabox in the Topics and Replies back-end. Just check the box and click Update and the notifications will be triggered.
Once you get the message out, check your test mailbox (the one that usually receives the notifications, not the one you set up for RBE). Once the notification arrives, make sure RBE modified it for its needs. This is what you should look for:
- The body of the message contains a paragraph that says
##- If you want to reply, type it above this line -##
- The reply-to header has been set and is the email account you set up for RBE along with +usc_ and a bunch of characters before the @.
If you’re seeing that, then things are looking good. If you’re not, feel free to contact support and we’ll take a look.
Go ahead and reply to that message. The To field should show the special RBE address. If it doesn’t and you’re using Gmail, refer to the warning above. Write anything you want in the message above that special paragraph and send the message. Check the RBE mailbox to see if the message gets there, but don’t open it! RBE looks for unread messages for performance reasons.
The First Run
So you now have a message waiting in the RBE mailbox. How do you test if it’s going to work?
That’s actually quite simple. First make sure your Check Method is set up for Webhook (save the settings!). Then copy the Webhook URL (blurred in the image above) and paste it in a new browser tab/window. You should end up with a message depicting how many emails were processed. If none were processed and you saw the unread message in the RBE mailbox, please contact support. If you had too many unrelated messages in the mailbox, it could be that the script timed out while sifting through the pile looking for the emails to post. That’s why it’s important to have a dedicated mailbox just for RBE.
Go to the topic where you expect your reply to be and see if it’s there.
Depending on the email client that you used to send your reply, you may see some spurious text after the reply. That’s because some email clients add weird stuff between the actual message and the special paragraph. We have lots of code working to remove that weird stuff, for most of the common email clients actually, but some more obscure ones may still pose an issue. If that’s happening to you, please contact us so we can adjust the plugin accordingly.
Feel free to reply to your reply in the front-end and send another reply to the reply to the reply… (I lost count) via email. Once you’re satisfied with the functionality, it’s time to automate it.
To Cron or to Webhook
RBE will let you automate it in several ways. They all involve either Cron Jobs or third-party integration (with
IFTTT, Zapier, etc.). You can even use the WordPress Cron by itself if you want, but we don’t recommend that unless you have LOTS of traffic.
You can follow this link to read up on how to set up this section, but the simplest thing is to use a Real Cron job along with the Webhook URL. Most hosts offer some sort of real cron job interface (such as cPanel). Siteground (my favorite host so far) has a good tutorial on how to set up real cron jobs in cPanel for WordPress. The steps for the webhook are pretty much the same, but the actual command that’s run is different. It’s a good idea to follow the steps outlined in that tutorial to replace the WordPress internal Cron job (just follow the steps to the letter), and then follow them again (skipping the DISABLE_WP_CRON part, which is done only once) and using the following command instead of the original one:
wget -q -O - https://yourdomain.com/?bbpnnsrbe-run=thesecretkey >/dev/null 2>&1
https://yourdomain.com/?bbpnnsrbe-run=thesecretkey in the command with your Webhook URL.
Make sure that you still have Webhook set as Check Method or you’ll get an HTTP 400 error when the cron job runs.
Only use the WordPress Cron method if you’re NOT going to use the Webhook URL anywhere and will depend on WordPress to try to respect the check frequency.
If you managed to get this far unscathed, the rest is smooth sailing. The remaining settings in this section and in the Message Processing section are pretty much self explanatory. If you choose not to delete read messages, RBE will try to move them to a special folder in your mailbox (if you’re using IMAP which is the default for Gmail and Outlook) so as to be able to process newer messages faster.
The options in the Message Processing section are mostly site owner preferences to limit what can or cannot be posted into the forums.
Topics by Email!
Version 1.9 of RBE introduced the ability to create topics via email. You’ll have to enable it in the General Settings tab.
Once you do, your users will start seeing little envelopes in the forum list screens with “mailto:” links. The email address is unique for each forum/user combination, so it won’t show up unless the user is logged in.
Any email sent to the special email address will end up becoming a new topic in that forum.
The special address also shows up in the back-end Edit Forum screen, inside the metabox where you find forum type, status, parent, and order.
You will *not* see it in categories or the new forum screen.
Subscription Integration Settings
This part helps RBE notify everyone who needs to be notified when a reply to a new topic is posted.The section fully explains what each option does. We recommend setting this to Use bbpnns Rules, if you’re happy with your bbpnns setup and don’t have any membership plugins installed.