Troubleshooting email on a new Discourse install

(Jeff Atwood) #1

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!


Why email error sending? Discourse does not connect to SMTP
Can't get email to send?
Test email working but activation mail not working
SMTP email configuration is not working
Test email not sending, 'completed 422 unprocessable entity' in production.log
JSON parse error when sending email with SparkPost
Email to verify new administrator not arriving
Can't get admin email to send working with using namecheap email server
Amazon SES not working with Discourse new install
Logs: Job Exception
Did one-click install on Digital Ocean. Set up SMTP using SparkPost. Not receiving Discourse activation email
User invites are not reaching destinations
Email confirm not sent with docker
What happens if you dont install email on Discourse
Need Help - Discourse New Installation Forum Mail Not Working
Confirmation Email Not Sent To User
Discoure with Amazon ses
Need Help - Discourse New Installation Forum Mail Not Working
Trying to use googles SMTP
Discourse Setup - Not receiving activation email
Local host as domain server?
Hard time setting up the SMTP
Discourse server failing to send email to the initial registered user
Discourse server failing to send email to the initial registered user
Mailgun test email goes to spam due to blacklist
Creating user without send out e-mail
Testing SMTP and watching logs?
Automatic activation for users
User should be able to login without verification
Continue Discourse Installation
Set up some email
Emails suddenly stopped being sent
To send email from you need to etc
Not able to send emails - board offline until I can fix
Amazon SES: "Must issue a STARTTLS command first"
503 AUTH command used when not advertised
Testing SMTP and watching logs?
Can not configure my Bitnami Discourse instance to send out mails
Trouble getting the first email from Discourse
Another 'cannot get smtp working' thread
Am I missing anything?
New Discourse Instance, Email not working
[Self Hosted Install]
Emails are being sent as localhost.localdomain
Unable Receive Activation Emails
Questions about using Discourse in a small (<10 people) community
Fresh install on VPS can't receive email
Is there a good information about Discourse configuration?
Service email not woking
Emails spontaneously broken
Relocation of server caused e-mail send out to fail
Error while rebuilding
Discourse forum sometimes loads with "Index of /" sometimes correctly with its signup/ login page
Trouble configuring DNS
Better cleanup script
E-mail didn't delivered in the easyengine(nginx) proxy mandrill environment
Installing discourse and connecting it to cloudflare
Dont Get Activation Email When Signing Up
Cannot get email working on new install
(Jeff Atwood) #2

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 an 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 still doesn’t work! What next?

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


Email sends but isn't received
SMTP, Exchange Server problem
Emails not being sent out
Create a unified, global setting for sender address
No matter what I do, can't get email working on new install
Discourse installed, E-Mail problems
Email not working after finished setting discourse
Email to verify new administrator not arriving
Following the setup instructions, so close! Error at very end!
Email not received for admin verification
Test e-mail "sends" but only I (the creator of the forum) can receive it
Anyone using gmail for SMTP?
Error connecting to Redis on localhost
SMTP connection problem, docker installation
Is there a good information about Discourse configuration?
“Sidekiq is not running” Email error
"There was a problem sending the test email."
“Sidekiq is not running” Email error
OAuth Email missing in data explorer
No admin email sent after 30 minute install
How to setup relay smtp from google on discourse
Amazon SES: "Must issue a STARTTLS command first"
Discourse not sending Emails
Cannot get email working on new install
Not getting confirmation mail due to .tk domain name
Help, do not send the email
Log says mail is sent! but it's not
Emails are apparently working but they are not really sent
No admin email sent after 30 minute install
No admin email sent after 30 minute install
(Anton) #114

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 [Wiki] | NDCHost

  2. How to send an email from telnet:
    14.04 - How to test out the SMTP Server? - Ask Ubuntu

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


(edoceo) #127

I host my own MTA via Postfix; after installing Discourse it cannot send any email through my MTA. The reason is that when Discourse connects to send it announces SMTP HELO with “localhost.localdomain” and I have Postfix configured to reject obviously bogus hostnames.

It seems that Discourse should use the hostname from what I’ve defined in the Docker configuration (

But, with Postfix you can also configure the Discourse host to be more trusted by adding it to the my_networks option of Postfix - so that the invalid hostname on HELO can be ignored.

1 Like

Anyone using gmail for SMTP?
(Régis Hanol) #267

I don’t think there’s a rake task, but you can run this in the rails console "")

(Anton) #291

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


(Jeff Atwood) split this topic #305

19 posts were split to a new topic: Cannot get email working on new install


Cannot get email working on new install
(Jay Pfaffman) #306

Easier than opening a ticket is using port 2525. I use it by default on my installs and never have a problem.


(Kane York) split this topic #307

4 posts were split to a new topic: Can send email from command-line but not Discourse


(Jim Ehrlich) #308

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.


(Brahn) #319

In case it helps anyone here, this was the solve for an installation unable to get emails to deliver.
They wanted to use their CPanel server for outgoing mail and it just wasn’t working.

Cpanel gives you details like this:

Which led to an app.yml like this:


way too much hacking later and I got that working by doing this in the rails console.


:bulb: :blush: ok, so now I actually read up on the fun that is STARTTLS

The correct configuration is to use the scary looking NOT Recommended outgoing port of 587 (yes, the discourse default) and let STARTTLS do it’s thing.

Also, people often don’t know how to setup SSL on their shared cpanel servers for mail so you will likely experience certificate warnings which will also stop this from working.

Final settings needed:

#DISCOURSE_SMTP_PORT:                    # (optional, default 587)
#DISCOURSE_SMTP_ENABLE_START_TLS:         # (optional, default true)

Seems obvious but there was nothing in the logs that helped identify the reason for the problem other than it just doesn’t work.


(Ruth Cheesley) #320

I seem to be having a problem since enabling SSL via the one-click install on Digital Ocean via the documented route of rebuilding discourse. SSL is working fine, but my SMTP mailer (using Sendgrid) started throwing errors.

With the original settings which were working fine pre-SSL, I get the following error:

Jobs::HandledExceptionWrapper: Wrapped Net::SMTPAuthenticationError: 535 Authentication failed: The provided authorization grant is invalid, expired, or revoked

I tried to create a new API key just to rule out some issue there, but still no joy.

Attempting to use Port 465 (after rebuilding app), I get the following error:

Jobs::HandledExceptionWrapper: Wrapped Net::ReadTimeout: Net::ReadTimeout

Any ideas? Thanks in advance


(Blake Erickson) #321

I’m not sure about the “one-click” install or why things were working before, but not now. However, I also use sendgrid and these are the settings that I have:

port: 587
user_name: apikey
password: <api-token>
1 Like

(Ruth Cheesley) #322

Thanks - that’s exactly what I had and was working fine.

Then I needed to enable SSL (it wasn’t enabled before in the Digital Ocean ‘one click’ app), and I was directed to follow the instructions here and run the command:


Still trying to get to the bottom of it, as I guess it could be at Sendgrid’s end so have opened a ticket there as well.


(Alkaline Thunder) #323

If none of the troubleshooting steps in this thread help you fully diagnose and fix issues with SMTP, like in the case with me, I wrote a little program you can use to send a test email using your SMTP credentials, without going through Discourse to do so. It’s written in C# though, so, you’ll need mono.

To use it, run ./launcher enter app to get a shell into your container.

Then, use wget to download my program to your container (you may need to install wget using apt-get install wget). You can download it from

Then, run:

# Install Mono into your container so you can run C# programs
apt-get install mono-complete
# Run the test utility
mono ./SMTPTestUtility.exe

It’ll ask you for your SMTP hostname/port, your “from” address, the recipient address, your SMTP username and password, and whether or not to use TLS/SSL for the connection. Then it will attempt to send an email to the recipient using that information and if it succeeds you will see the program simply output “Press any key to continue…”.

If you DO get an error, you’ll get a C# stacktrace and exception message telling you exactly what went wrong. I’m not sure about Ruby, but C# does hierarchical exceptions - each exception can have an InnerException property which can provide more information about what caused its parent exception. So keep reading down the hierarchy and eventually you’ll find the lowest-level error. That should tell you a bit more about what the frick is going on with SMTP on your container.

If you are worried that this is actually malware, well, fear not. This is the exact source code of that program. If you’re absolutely worried, you can compile it yourself.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Mail;
using System.Text;
using System.Threading.Tasks;

namespace SMTPTestUtility
    class Program
        static void Main(string[] args)
            Console.Write("SMTP server hostname: ");
            string host = Console.ReadLine();
            ushort port = 0;
            Console.Write("SMTP server port: ");
            while (!ushort.TryParse(Console.ReadLine(), out port))
                Console.WriteLine("That's not a valid port.");
                Console.Write("SMTP server port: ");

            Console.Write("\"From\" address: ");
            string from = Console.ReadLine();
            Console.Write("Recipient: ");
            string to = Console.ReadLine();
            Console.Write("SMTP username: ");
            string user = Console.ReadLine();
            Console.Write("SMTP password: ");
            string pwd = Console.ReadLine();

            Console.Write("Use TLS/SSL? [True|False] (blank for true): ");
            bool tls = true;
            string answer = Console.ReadLine();
            if (!string.IsNullOrWhiteSpace(answer))
                if(!bool.TryParse(answer, out tls))
                    Console.WriteLine("Not a valid answer.");
                    goto useTLS;

                var mailer = new SmtpClient(host, port);
                mailer.EnableSsl = tls;
                mailer.UseDefaultCredentials = false;
                mailer.Credentials = new NetworkCredential(user, pwd);
                mailer.Send(from, to, "This is a test", "If you're seeing this then, at least SparkPost is working. Why isn't Discourse?");
            catch (Exception ex)
                Console.WriteLine("Press any key to continue...");

(Tom) #326

For what it’s worth.
My problem (which I’ve solved) was the discourse smtp user not having permission to send from the discourse sub-domain:

  1. Setup discourse at ‘
  2. Using a mailserver based on the ISPMail guide
  3. Setup the discourse login e-mail as ‘’
  4. Try to send the activation e-mail, but nothing is received
  5. Review the mailserver logs and finde:
    Nov 11 02:50:49 ip-172-26-5-8 postfix/submission/smtpd[26131]: NOQUEUE: reject: RCPT from unknown[]: 553 5.7.1 <>: Sender address rejected: not owned by user; from=<> to=<> proto=ESMTP helo=<localhost.localdomain>
    In particular: not owned by user
  6. Try and setup an alias to allow e-mail sending: ->
  7. Eventually realise that even though the alias is setup, that I am only allowing the logged in user to send as themselves (via this postfix configuration):
    -o smtpd_sender_login_maps=mysql:/etc/postfix/
  8. Allow aliases to send:
    -o smtpd_sender_login_maps=mysql:/etc/postfix/,mysql:/etc/postfix/
  9. restart postfix and everything works.

(Bhanu Sharma) #327

You could’ve simply specified the notification email in the yml file and saved much hassle.


(Kim Miller) #332

I’ve backed up a Digital Ocean production instance and restored it to a local Mac (not using Docker) instance. I now want to edit app.yml to get email working for local testing, but don’t see it in my local install. Is there a recommended way to set up the app.yml for a Mac localhost?


(William Entriken) #333

WARNING: “Rebuilding your app”, whatever that means, takes a very long time. This is not a painless 30-minute process as advertised. And there is no way I could have talked my grandmother through this process over the phone in less than one week.

I think choosing as a silent default for sending emails is a poor choice. Instead this should be explicitly asked from the admin when they are first installing the software. I will choose or something that /already/ works with my existing SMTP setup.


(Jeff Atwood) #334

Do you mean “as a silent default for the return address of sent emails” ? Because unless your email provider loses its mind based on the return address, it shouldn’t matter that much.

Haven’t seen many problems with this, let’s see if @pfaffman has an opinion.