You just installed Discourse via the install guide, but email doesn’t seem to work. Unfortunately this means you can’t log in as an admin to finalize the install. Let’s troubleshootize!
If you run
./discourse-doctor it will check several ways that your mail configuration might be broken, and offer advice. Try that first.
The simplest way is to run
./discourse-setup again. Did you enter everything correctly?
You can also double check the settings in your
containers/app.yml file. A valid email section looks like this:
DISCOURSE_DEVELOPER_EMAILS: 'firstname.lastname@example.org' DISCOURSE_SMTP_ADDRESS: smtp.mailgun.org DISCOURSE_SMTP_PORT: 587 DISCOURSE_SMTP_USER_NAME: email@example.com DISCOURSE_SMTP_PASSWORD: aUd34cdWKCu6CTjfoH7ykk
Closely examine all values for correctness. Note that it all aligns, there are no leading
# characters, and there are single quotes around the developer email field.
If you had any errors in your
app.yml and made changes , you MUST rebuild the container for those changes to take effect!
cd /var/discourse/ ./launcher rebuild app
Doing a rebuild will often fix things that seem broken, but it takes a while. There are times when a full rebuild is not necessary; the above is usually the best advice, but If you change just SMTP settings, you can do just this to apply them without doing a full rebuild:
cd /var/discourse ./launcher destroy app ./launcher start app
To confirm that your server can indeed contact the email server, issue this command:
telnet smtp.mailgun.org 587
If you can’t connect this way, you’re almost certainly blocked. (And if you do get connected, the escape character for SMTP is ctrl+], then use
quit to exit telnet.)
If this happens, contact your cloud provider support and confirm that your email connections are not being blocked.
From the command line, issue this command:
cd /var/discourse tail shared/standalone/log/rails/production.log
This will show the last few lines of the log. Look for anything mail related. If you need to view the fuller logs, try
To page through the complete log by pressing space. Look closely for any email related messages.
Assuming there are no errors in the Discourse logs, or your Discourse mail configuration, the emails probably went out. The question, is what did your email provider do with them?
Most email providers have a log viewing function. Check the logs for your email domain and see what happened with the incoming emails.
You must enter those crucial DNS records for DKIM and SPF, otherwise your emails may arrive only sporadically, if at all.
The default email from address is based on the install domain plus subdomain, so if your URL is
discourse.example.com it will be:
But if your mail provider is expecting:
… you may have problems! To get around this, edit and uncomment this line in
## If you want to set the 'From' email address for your first registration, uncomment and change: #- exec: rails r "SiteSetting.firstname.lastname@example.org'" ## After getting the first signup email, re-comment the line. It only needs to run once.
You’ll need to issue a rebuild after uncommenting the above line and setting the from email address as required.
You can also change this from the command line, if needed:
./launcher enter app rails r "SiteSetting.notification_email = 'email@example.com'" exit
If you are using Mailgun, after you enter your DKIM and SPF records, you must visit
https://mailgun.com/app/domains/YOUR.DISCOURSE.DOMAIN.com and click the “Check DNS Records Now” button. At the top of that page you should see “State ACTIVE” (in a calming green). If it says “State Unverified” (in a scary warning-yellow) Mailgun will not accept mail.
Mailgun now requires a credit card in order to deliver mail (other than to you). If your mailgun logs have a message about “free accounts,” this is your problem.
Other mail services have similar requirements.
This does not work in our experience. You must use a domain name when sending email, not an IP address like
If you really want to go on with an IP address, try mail settings similar to these:
DISCOURSE_SMTP_ADDRESS: 172.17.0.1 # e.g. use internal docker IP here DISCOURSE_SMTP_PORT: 587 DISCOURSE_SMTP_USER_NAME: "YOUR-SMTP-USER-NAME" DISCOURSE_SMTP_PASSWORD: "YOUR-SMTP-PASSWORD" DISCOURSE_SMTP_ENABLE_START_TLS: true # (optional, default true) DISCOURSE_SMTP_OPENSSL_VERIFY_MODE: none DISCOURSE_SMTP_DOMAIN: example.com
We don’t recommend this, because your email is still broken, and you have a broken Discourse until email is working. But if you absolutely must log in as admin with email broken, here’s what to do:
cd /var/discourse ./launcher enter app rake admin:create
And answer the prompts. It takes a few seconds before they appear. When it asks for the password, you will not be able to see what you type. That is why it makes you type it twice.
The ability to be able to AUTH using ‘telnet’ is extremely important in your first steps of email troubleshooting.
Port 465 (SMTP over SSL) is largely deprecated in favor of STARTTLS on 25. You may need to try alternate ports such as port 2525 or port 587 (Mail Submission) when things do not seem to work as expected.
If you’re comfortable with the command line, these might help diagnose network or certificate problems. If these do not seem “easy-to-follow” then you should please ignore this section.
If you’re using Office 365, be sure to include these (the first line is what you are likely missing):
DISCOURSE_SMTP_AUTHENTICATION: login DISCOURSE_SMTP_ENABLE_START_TLS: true DISCOURSE_SMTP_PORT: 587
and set the correct
notification_email (which is likely different from your forum hostname).
Anything else I forgot here? Feel free to edit this.
./launcher enter app
ping etc. are not installed inside the container.)
getent hosts your.smtp.server
Result on success:
# IPv4 220.127.116.11 your.smtp.server # IPv6 2001:db8:0:0:0:ff00:42:8329 your.smtp.server
nc etc. are not installed inside the container.)
Fiddle with some different settings until you succeed with a connection.
openssl s_client -connect your.smtp.server:465 openssl s_client -connect your.smtp.server:587 -starttls smtp # IPv4 openssl s_client -connect 172.17.0.123:465 openssl s_client -connect 172.17.0.123:587 -starttls smtp # IPv6 openssl s_client -6 -connect "[2001:db8:0:0:0:ff00:42:8329]:465" openssl s_client -6 -connect "[2001:db8:0:0:0:ff00:42:8329]:587" -starttls smtp
ip etc. are not installed inside the container.)