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!

Let’s troubleshootize!


Did you enter email settings correctly?

Double check the settings in your containers/app.yml file; the simplest way is to run ./discourse-setup again. A valid email section looks like this:


Double-check 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 run ./discourse-doctor it will check several ways that your mail configuration might be broken.

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 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 it will be:

But if your mail provider is expecting:

… 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=''"
## 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 = ''"

If you are using Mailgun, have you activated your domain and provided credit card information?

If you are using Mailgun, after you enter your DKIM and SPF records, you must visit 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

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

The ability to be able to AUTH using ‘telnet’ is extremely important in your first steps of email troubleshooting. You may need to try alternate ports such as port 2525 or port 587 when things do not seem to work as expected.

Email still doesn’t work! What next?

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


Just a few more links on sending an email through telnet:

  1. Easy-to-follow tutorial on how to authenticate with SMTP server from telnet:
    How to Test SMTP AUTH using Telnet

  2. How to send an email from telnet:

Followed these two and successfully sent an email with Mandrill SMTP.

Another option to manually check email deliverability in a more simplified way is to use Swiss Army Knife SMTP, the all-purpose smtp transaction tester (swaks) rather than telnet.

Example command:

swaks --to --from --server --auth LOGIN --auth-user -tls


It might be useful to add to the guide that a normal log for a sent message looks like this

Sent mail to **** (413.2ms) Rendering text template Rendered text template (0.0ms) Completed 200 OK in 576ms (Views: 0.9ms | ActiveRecord: 16.2ms)

… and If you still do not receive mail, check the “skipped” tab of admin-email settings, i.e /admin/email/skipped

In my case, AWS-SES was rejecting messages because my “reply by email” address was incorrect, which was apparent from the error message found on the skipped tab. There is a catch, however. Failed test messages do not show up in skipped. I was only able to see the error message because there were attempts to send digests that also failed for the same reason. I could find no record of the test message fails in /admin/email/. Maybe this is a bug.

Finally, when I finally do get the test message I get some helpful hints that I can only read after the problem is fixed. That template text should be in this guide, not a message you cannot read until you have found the fix.


How do I add DKIM and SPF records? I don’t see an option in DNS settings.

They’re usually TXT or sometimes CNAME records. Your email provider should tell you exactly what to add.


I use so should I not use mailgun?
nder emails it haas the SMTP server stuff, so should I enter that and create a new email address hosts my domain, emails and DNS

Looks like you can use’s email server to send email for Discourse, but this page says they have a limit of 25 emails / 5 minutes, and anything but the smallest forum would send more emails than that (on occasion, not constantly.) That’s why Mailgun, AWS SES, etc are recommended.

So you can probably give it a try, but be prepared that you might have to switch later on as your forum grows.

1 Like

This should really be pinned and be linked in the official guide for discourse installation on github. A few things I will say that I learned as of July 2020.

  1. People have recommended many different free SMTP providers. I would recommend SendGrid. it allows 40,000 emails in the first 30 days and 100/day after that.
  2. If your smtp isn’t working, try sending an email using telnet. First authenticate and then send an email. Telnet helps a lot in finding the issue.
  3. The issue for me was the “from” email. The sender email has to be accepted by your SMTP provider. I had to add a sender to SendGrid and then verify that. Then, I had to uncomment the line in the app.yml so that I could put that same sender email.
  4. You can’t use a sender email that you don’t have access to or a domain that you don’t control.
1 Like

If all else fails, try this

Look for this line in the app.yml file

#DISCOURSE_SMTP_ENABLE_START_TLS: True # (optional, default true)

Now change it to this:

DISCOURSE_SMTP_ENABLE_START_TLS: false # (optional, default true)

Now rebuild the app

cd /var/discourse/
./launcher rebuild app
1 Like

The email account must be created or existing on your email provider.

Discourse does not create email accounts for you on external email systems.

Hope this helps you move forward in your install.

1 Like

I found a solution to get my activation email to work. It involves making a few specific and peculiar edits to the app.yml file, as outlined on this page: