Troubleshooting email on a new Discourse install

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. :cry: Let’s troubleshootize!

Try the doctor :woman_health_worker:

If you run ./discourse-doctor it will check several ways that your mail configuration might be broken, and offer advice. Try that first.

Did you enter email settings correctly?

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: 'name@example.com'
DISCOURSE_SMTP_ADDRESS: smtp.mailgun.org
DISCOURSE_SMTP_PORT: 587
DISCOURSE_SMTP_USER_NAME: postmaster@discourse.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

Are your SMTP connections being blocked?

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.

What do the Discourse logs say?

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

more shared/standalone/log/rails/production.log

To page through the complete log by pressing space. Look closely for any email related messages.

What do your email provider logs say?

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.

Did you properly set up DKIM and SPF records for your domain?

You must enter those crucial DNS records for DKIM and SPF, otherwise your emails may arrive only sporadically, if at all.

Is the email domain correct?

The default email from address is based on the install domain plus subdomain, so if your URL is discourse.example.com it will be:

noreply@discourse.example.com

But if your mail provider is expecting:

noreply@example.com

… you may have problems! To get around this, edit and uncomment this line in app.yml

## If you want to set the 'From' email address for your first registration, uncomment and change:
#- exec: rails r "SiteSetting.notification_email='noreply@example.com'"
## 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 = 'discourse@yoursite.com'"
exit

If using Mailgun – have you activated your domain and provided credit card info?

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.

Are you using an IP address as the mail domain?

This does not work in our experience. You must use a domain name when sending email, not an IP address like 192.168.1.1.

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

Need to log in without receiving a registration email?

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.

Email smtp port selection (Using 465?)

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.

Command Line SMTP tests for experienced sysadmins

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.

See also How to test SMTP Authentication and StartTLS - Sysadmins of the North.

Office 365 Tweaks

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).

Email still doesn’t work! What next?

Anything else I forgot here? Feel free to edit this.


Debug issues with first connection to smtp server from inside the Discourse container

1. Enter your container:

./launcher enter app

2. Check dns resolving for your smtp server name via getent hosts:

(dig, nslookup, ping etc. are not installed inside the container.)

getent hosts your.smtp.server

Result on success:

# IPv4
123.123.123.123 your.smtp.server

# IPv6
2001:db8:0:0:0:ff00:42:8329 your.smtp.server

3. Try to open a connection to your smtp server via openssl:

(telnet, 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

See: How to check SMTP connection → Step 3: Checking SMTP Connection Over TLS Using Openssl

4. Use your found working connection settings with Discourse.

:rocket:

Bonus: show Discourse IP from inside docker container

( ifconfig , ip etc. are not installed inside the container.)

hostname -I

Result like:

172.17.0.2
46 Likes
I am not getting any emails
Unable to send email
Mail system not working even thought I tested it with telnet and other platforms
Post Install Email Issues
Installing Discourse on DigitalOcean - got stuck
Activation email not being delivered, test email working
Announcing Discourse Doctor
Errors with Sidekiq - emails not sending
Discourse SMTP not receiving mails?
All files and directories disappeared from root
How might we better structure #howto?
Mail doesnt work after installation
Email installation issue
I did not receive an email to activate my account
Emails are not sent
New signups not receiving welcome email
Discourse with other websites, SMTP issue: End of file reached
Setup wont send me the email
Not Receiving Email for Admin Creation
Siteground email
Update failed - Not starting
Discourse SMTP Error
SMTP do not work
Email config help
Email error: Connection reset by peer
Email delivery configuration checklist
404 Error after installaton
Trouble setting up smtp
Post Install Can't complete email verification
After Installation Discourse is unable to send Verification email
I created a droplet to install Discourse, what should I do next?
Discourse 云平台安装
Unable to find verification email
MKJ's Opinionated Discourse Deployment Configuration
After Installation Discourse is unable to send Verification email
New install email not working "shadowed so this will be ignored"
Email not sending after update
Mail error 504 5.7.4 Unrecognized authentication type
Database shut down error at the end of discourse docker setup
E-Mail not working after moving to self-hosting and adding DKIM record
SMTPAuthenticationError: 535 Incorrect authentication data
Issue on Discourse Digest Email
Letters are not sent. What to do?
Sidekiq email errors and settings issue
How do I Change Email Adress in admin/settings/emails?
Noob installation : email not working, trouble with the digitalocean console
Outgoing/incoming email changes for our hosted customers
Can't Send Emails
Editing posts cause notification
Email Hostname Certificate Mismatch Causing sidekiq Queue Overload, Severe Site Instability
Activation email on Spam
Admin activation E-Mail not sent on fresh self-hosted install (ubuntu 20.04)
Recommended SMTP provider
Problem with changing password from mail
Discourse on Azure VM
Email not sending - Domain Spoofing Prohibited
DNS - NameCheap - Mailchimp - sanity check please
Problem with changing password from mail
Waiting the activation email, been hours still not received
Not getting activation email
I have a question about configuring the mail system
Connecting to a SMTP server on localhost:25 without auth?
SMTP error: Must issue a STARTTLS command first
Connecting to a SMTP server on localhost:25 without auth?