Discourse is all about enabling civilized discussion. While plenty of people like a web interface, e-mail is still the “hub” of many people’s online lives. That’s why sending e-mail is so important, and when you’re sending e-mail, you really want to be able to receive it, too. There are several reasons why:
- If e-mails “bounce” (they can’t be delivered for some reason), you need to know about that. Repeatedly sending e-mails that bounce will get your e-mails flagged as spam. Receiving e-mail bounces allows you to disable sending to non-existent addresses.
- Allowing people to reply to posts via e-mail can significantly improve engagement, as people can reply straight away from their mail client, even if they’re not able to visit the forum at that moment.
- Letting people post new topics, or send PMs, via e-mail has similar benefits to engagement. In addition, you can use Discourse to handle e-mail for a group, such as an e-mail-based support channel (which is how Discourse’ own e-mail support is handled).
Delivering e-mail directly into your Discourse forum, rather than setting up POP3 polling, has a number of benefits:
- No need to deal with gmail or another provider’s foibles;
- You have more control over the e-mail addresses that people use to send posts; and
- There are no delays in delivery – no more waiting for the next polling run to see new posts appear!
This howto is all about getting that hawtness into your forum.
This procedure creates a new container on your Discourse server, alongside the typical
app container, which receives e-mail and forwards it into Discourse for processing. It supports all e-mail processes: handling bounces, replies, and new topic creation. Any self-hosted Discourse forum using our supported installation process can make use of this procedure to get easy, smooth-flowing incoming e-mail.
We’re going to get the
mail-receiver container up and running on the server that’s already running your Discourse instance. There’s no need for a separate droplet just to handle mail – the whole container only takes about 5MB of memory!
So, start off by logging into your Discourse server, and becoming
ssh email@example.com sudo -i
Now, go to your
/var/discourse directory and create a new
mail-receiver.yml container definition from the sample conveniently provided:
cd /var/discourse git pull cp samples/mail-receiver.yml containers/
Since every site is unique, open
containers/mail-receiver.yml in your preferred text editor and change the
DISCOURSE_API_KEY variables to suit your site. If you’re not sure what your favourite text editor is, try
Ctrl-X to exit (say “Yes” to “Do you want to save changes?”, or all your work will be for nothing).
Now, do an initial build of the container, and fire it up!
./launcher bootstrap mail-receiver ./launcher start mail-receiver
To check everything’s OK, take a peek in the logs:
./launcher logs mail-receiver
The last line printed should look rather a lot like this:
<22>Aug 31 04:14:31 postfix/master: daemon started -- version 3.1.1, configuration /etc/postfix
If so, all is well, and you can go on to then next step.
In order for everyone else on the Internet to know where to deliver mail, you must create an
MX record for your forum. The exact details of how to do this vary by DNS provider, but in general, the procedure should be very similar to how you setup the DNS records for your forum in the first place, except that instead of creating an
A (or “Address”) record, you’re creating an
MX (or “Mail eXchange”) record. If your forum is at
forum.example.com, and you set
forum.example.com in the
mail-receiver.yml, then the DNS record should look like this:
forum.example.com(this is the
- Priority: 10
forum.example.com(this is the domain of your forum)
To make sure the DNS is setup correctly, use a testing site such as http://mxtoolbox.com/ to look up the
MAIL_DOMAIN you configured, and make sure it’s pointing to where you expect.
You can also now try sending an e-mail to
firstname.lastname@example.org. While Discourse won’t do anything useful with it yet, the e-mail you sent should show up in your admin panel under “Emails”, “Rejected” in a matter of seconds. If that happens, you’re definitely ready to proceed.
Now e-mail is being fed into Discourse, it’s time to explain to Discourse what to do with the e-mail it receives. For the most part, this is identical to setting up incoming e-mail via POP3 polling, with a few minor exceptions:
- Enable the “manual polling” setting, rather than “pop3 polling”; and
- You can automatically, without any further setup, use any address
@forum.example.comas an address for category or group e-mails.
Nothing ever goes according to plan. Here’s how to figure out what went wrong.
Did the e-mail even make it to
./launcher logs mail-receiver, and look for log entries that mentions the address that the e-mail was sent from and to. If there’s none of those, then the message never even made it, and the problem is upstream. Check MX records and sending mail server logs.
Is the message stuck in the queue? Run
./launcher enter mail-receiver, then run
mailq. It should report, “Mail queue is empty”. If there’s any messages in there, you’ll get the to/from addresses listed. Messages only sit around in the queue if there’s a problem delivering to Discourse itself, so
exitout of the container and then check…
mail-receivererror out somehow? Run
./launcher logs mail-receiver | grep receive-mailand look for anything that looks like a stack trace, or basically anything other than “Recipient: <something>@forum.example.com”. Those error messages, whilst not necessarily self-explanatory, should go an awfully long way to explaining what went wrong.