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:


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 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 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 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 (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):


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.

I am not getting any emails
Unable to send email
Post Install Email Issues
Mail system not working even thought I tested it with telnet and other platforms
Installing Discourse on DigitalOcean - got stuck
Activation email not being delivered, test email working
All files and directories disappeared from root
Announcing Discourse Doctor
Discourse SMTP not receiving mails?
Errors with Sidekiq - emails not sending
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
Problems with E-Mail after installation of discourse
Editing posts cause notification
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
SMTPAuthenticationError: 535 Incorrect authentication data
Issue on Discourse Digest Email
Trouble setting up smtp
Admin activation E-Mail not sent on fresh self-hosted install (ubuntu 20.04)
Problem with changing password from mail
Discourse on Azure VM
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
SMTP error: Must issue a STARTTLS command first
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

Error msg:

Delivered mail (30004.9ms)
Job exception: execution expired

Delivered mail (30002.4ms)
Job exception: execution expired

  Rendered layouts/email_template.html.erb (Duration: 0.1ms | Allocations: 30)
Delivered mail (30002.3ms)
Job exception: execution expired
1 Like

I tried removing double quote of the password but also didn’t work:

#DISCOURSE_SMTP_ENABLE_START_TLS: true # (optional, default true)
1 Like

change this

to this

and rebuild. see if that works


Someone else is probably better to help you on this, but the only place I can find that exception is when it has problems with the SMTP Port - @IAmGav 's solution will potentially fix that. If it doesn’t see if your SMTP provider has an alternate port you can use, I know MailJet has several port options I can use in case one is being blocked.

1 Like

like port 25? I’m using siteground…

1 Like

That would be one option for a Port, if they support it.

1 Like

tried changing to

Didn’t work

1 Like

port 25 also didn’t work

1 Like

Have you tried running ./discourse-doctor? It might shed more light on what is going wrong as well.

1 Like

Yes I tried.
With port 25 and 465 and 587, it’s showing

Sending mail to . . 
Testing sending to using, with plain auth.
======================================== ERROR ========================================
Connection to port 465 failed.
====================================== SOLUTION =======================================
The most likely problem is that your server has outgoing SMTP traffic blocked.
If you are using a service like Mailgun or Sendgrid, try using port 2525.

So I’m trying port 2525 now.

1 Like

Doctor checked failed but it works when registering.

It has a new error with port 2525:

Testing sending to using, with plain auth.
SMTP server connection successful.
Sending to . . 
Sending mail failed.
hostname "" does not match the server certificate
Replacing: Sending mail to
1 Like

Trying setting this DISCOURSE_SMTP_OPENSSL_VERIFY_MODE: none from here: Hostname does not match server certificate - #14 by michaeld

Still error:

Sending mail to . . 
Testing sending to using, with plain auth.
SMTP server connection successful.
Sending to . . 
Mail was not sent.

Reason: 550-Sorry The "MAIL FROM" email address
Replacing: Sending mail to

It seems that the email was identified as spam

1 Like

I believe at this point, with a 550 failure, you need to talk to SiteGround since they are your email host to figure out how to fix that.

Failing that there is a list of Recommended SMTP provider that specialize in sending this sort of mail.


I am encountering mail issue. I am using nginx, i’ve set up a working mail system with iredmail. I tried telnet localhost 587, that was okay, I saw the Postfix hello.
I used force Starttls for my Postfix, (disallowed auth over unsecured channel),so Starttls is a must. It’s a self signed certificate, I know it is working because i’ve set up roundcube webmail with Starttls.

However, discourse rigidly refuse to use Starttls. Here’s the doctor log.

    Sending mail to postmaster@mx.mydomain.tld. . .
    Testing sending to 
    postmaster@mx.mydomain.tld using  mail.mydomain.tld:587, username:discourse@mydomain.tld with plain auth.
======================================== ERROR ========================================
Connection to port 587 failed.

And here’s my config.

# SMTP ADDRESS, username, and password are required
  # WARNING the char '#' in SMTP password can cause problems!
  DISCOURSE_SMTP_ADDRESS: mail.mydomain.tld
  DISCOURSE_SMTP_ENABLE_START_TLS: true           # (optional, default true)
  DISCOURSE_SMTP_DOMAIN: mydomain.tld    # (required by some providers)

I own mydomain.tld and i used mydomain.tld to protect privacy.

I did run rebuild command.
No idea what’s wrong.

1 Like

Was your connectivity test made from inside or outside the container?

Have you confirmed that you can connect to postfix from inside the container?

1 Like

I would first get a legitimate certificate from let’s encrypt. Self signed certificates are bogus, so discourse refuses to use it. You could also contrive to copy your self signed credentials into the discourse container so that it would appear to be a legit certificate.


It was outside. Before replying i also did a test outside the container.
Failed, from inside, whether port 25or 587.
The point is that it can connect to a foreign host like, but not localhost, connection refused.
However the doctor seems to ignore the config

1 Like

If you can’t connect at all then it’s not an issue with the certificate but the connection.

If the mail server is on the same host as Discourse the you can’t use local hostv(that would be inside of the container) , you’ll need to use either the ip or the server or some docker-provided address, I think.

1 Like

Hi, could you please tell me all options I have debugging mail ?
At the moment I have this problem:

New Discourse Installation on Ubuntu on a Strato (German Provider) cloud instance (Docker Installation). It 2.8.0.beta7 and my mail settings are as such:

DISCOURSE_SMTP_ADDRESS: mail.iwonttellya.ever
DISCOURSE_SMTP_USER_NAME: discourse@iwonttellya.ever
DISCOURSE_SMTP_ENABLE_START_TLS: true # (optional, default true)
#DISCOURSE_SMTP_DOMAIN: mail.iwonttellya.ever # (required by some providers)
DISCOURSE_NOTIFICATION_EMAIL: discourse@iwonttellya.ever # (address to send notifications from)
DISCOURSE_CONTACT_EMAIL: myname@iwonttellya.ever

When I´m testing the mail over discourse admin dashboard I´m seeing this in production.log:

Processing by Admin::EmailController#test as /

Parameters: {“email_address”=>“myname@iwonttellya.ever”}

Rendered layouts/email_template.html.erb (Duration: 0.9ms | Allocations: 257)

Delivered mail f9bf5a3a-30e9-4bae-a998-62971acdc663@hostname.iwonttellya.ever (480.1ms)

Completed 422 Unprocessable Entity in 567ms (Views: 0.4ms | ActiveRecord: 0.0ms | Allocations: 27324)

But the mail never comes.

I tested it with swaks from host and from within container, and that works quite well.

swaks -f discourse@iwonttellya.ever -t -s mail.iwonttellya.ever:587 -tls -a LOGIN

So I tested around with different settings in app.yml, but didn´t succeed, yet.

What I wanted to ask now is, how to test it quicker?.

At the moment I´m rebuilding the container every time I change something on that smtp settings which takes about 10 mins every time :frowning:

Can you tell me how to set these directives directly without having to rebuild every time ?


P.S But any other hints on that problem would be appreciated as well :slight_smile:

1 Like