discourse/docs/INSTALL-email.md

Warning: This Guide is Deprecated

We only support Docker based installs now. Please see our official install guide for supported install instructions.

Discourse Mail Setup Guide

After following INSTALL-ubuntu.md your mailer settings should still be set.

Out-of-the-box Discourse is configured to deliver mail locally via sendmail.
That's great. Leave that there as we're going to try to get the mail to postfix
ASAP so postfix do it's job and process the mail for delivery.

Email is IMPORTANT

Email notifications are core to the Discourse experience. We want your users to receive notifications as soon as possible so they can contribute to the conversation.

If sending email isn't something to which you want to devote your time, don't
worry about it. There are companies that dedicate
theirs to doing one thing very well - ensuring that mail to your users gets
delivered.

Sending Email Through GMail

Don't do it! GMail is not intended for sending out bulk notifications. Your email setup will break.

Sending Email Through Mandrill

Create an account

We're going to use Mandrill as our email delivery
provider.

1. Create an account at http://mandrill.com/ (click on 'SIGN UP')

2. I filled out the 'Tell Us A Little About Yourself' survey. They are
   providing us a free service, after all!

Create an API key

I'm pleased with Mandrill's setup - this is the Right Way to do things.

1. Click 'Get SMTP Credentials'

1. Note that you can use 'any valid API key' as your password. Click '+ Add API Key' to create one.

1. Click 'Edit' to document for what we'll be using this key.

1. Since we'll only be using this key for sending email and nothing else, check 'Only Allow This Key To Use Certain API Calls' and select only Messages / Send and Messages/ Send-Raw. Send-Raw must be selected or Discourse won't be able to send email.

1. Optionally, restrict this key to the public static IP address of your server.

2. Click 'Save'

Configure Postfix for Mandrill

Thank you Mandrill for providing an excellent guide on configuring Postfix to use Mandrill.

Additional notes on this document:

• Ubuntu has an /etc/postfix/sasl directory. Create a password file in there.

• Make sure you put your API KEY into this password file, not your ACCOUNT PASSWORD

• You may already have configured a relayhost earlier in the installation. If this machine is sending out ANY emails other than Discourse-generated notifications, follow the instructions in 'Relay only certain emails through Mandrill'.

After configuring postfix as per Mandrill's instructions, reload postfix with sudo postfix reload.

Send test email

Now we send a test email. Login to your Discourse installation and click on the ≡ (aka congruence/hamburger/etc), then 'Admin'.

Click on Email, Settings, then type your email address into the test box and click send test email.

Within moments, you should have email in your Inbox.

OH NOES I DIDN'T GET MY EMAIL TEST!

Follow the trail. First of all, did the email get to Postfix? Check /var/log/mail.log:

Jun 24 01:24:59 discoursetest postfix/pickup[25387]: 7CBF280294C: uid=1001 from=<info@discourse.org>
Jun 24 01:24:59 discoursetest postfix/cleanup[25829]: 7CBF280294C: message-id=<51c7d82b6f878_8ef3d7802c10139@discoursetest.mail>
Jun 24 01:24:59 discoursetest postfix/qmgr[25386]: 7CBF280294C: from=<info@discourse.org>, size=5884, nrcpt=1 (queue active)

Looks good! Wait, why is the email coming from info@discourse.org? That's a
problem we'll fix below.

Jun 24 01:25:04 discoursetest postfix/smtp[25831]: 7CBF280294C: SASL authentication failed; server smtp.mandrillapp.com[54.235.146.179] said: 435 4.7.8 Error: authentication failed: 
Jun 24 01:25:10 discoursetest postfix/smtp[25831]: 7CBF280294C: SASL authentication failed; server smtp.mandrillapp.com[54.234.14.176] said: 435 4.7.8 Error: authentication failed: 
Jun 24 01:25:13 discoursetest postfix/smtp[25831]: 7CBF280294C: SASL authentication failed; server smtp.mandrillapp.com[50.16.10.62] said: 435 4.7.8 Error: authentication failed: 
Jun 24 01:25:20 discoursetest postfix/smtp[25831]: 7CBF280294C: to=<spoonman@discourse.org>, relay=smtp.mandrillapp.com[54.235.146.152]:25, delay=21, delays=0.07/0.01/21/0, dsn=4.7.8, status=deferred (SASL authentication failed; server smtp.mandrillapp.com[54.235.146.152] said: 435 4.7.8 Error: authentication failed: )

The above errors are caused by using an incorrect API key in your sasl passwords file. Fix that (edit /etc/postfix/sasl/passwd, run sudo postmap on it, then postqueue -f to restart the queue).

Jun 24 01:30:30 discoursetest postfix/smtp[25861]: table hash:/etc/postfix/sasl/passwd(0,lock|fold_fix) has changed -- restarting
Jun 24 01:30:31 discoursetest postfix/smtp[25872]: 7CBF280294C: to=<spoonman@discourse.org>, relay=smtp.mandrillapp.com[54.234.14.176]:25, delay=332, delays=331/0.01/1.2/0.17, dsn=2.0.0, status=sent (250 2.0.0 Ok: queued as C515B6380D3)

That's better! Our test message made it to Mandrill. Let's check Outbound Activity in Mandrill:

If you see this, the email was accepted by Mandrill and delivered to the
destination. You need to check your spam filter now.

If you don't see anything in Mandrill, ensure that the API key is enabled for
'Send-Raw' permission. Mandrill appears to silently drop the email if that's
not set.

Configure notification email addresses

Login to Discourse, go to the Admin page and select 'Settings'.

Filter with the string 'system'.

• Ensure that site_contact_username is set to an email address for an appropriate "owner" of the forum
• Set notification_email to 'noreply@', 'nobody@' as appropriate.

Filter with the string 'contact_email'

• Ensure contact_email is set appropriately.

SPF and DKIM records

Login to Mandrill and click on ⚙ (Settings)-> Sending Domains

If your domain isn't listed, add it. It'll probably show this:

Click 'View DKIM/SPF setup instructions'.

Follow the instructions there.

When DNS is properly configured, you should be able to click on 'Test DNS Settings' and Mandrill will confirm they are setup properly:

Mandrill Options

Login to Mandrill and click on ⚙ (Settings)-> Sending Options

• 'Track Clicks' is enabled by default. This rewrites links in email messages to bounce off the mandrillapp.com domain for click tracking. Disable it here if you don't want that:

• If you do use it, setting up a 'Tracking Domain' is a very good idea to avoid erroneous scam warnings: