# Troubleshoot email on a new Discourse install
**URL:** https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326
**Category:** Self-Hosting
**Tags:** email, configuring, how-to
**Created:** [June 7, 2014, 10:38pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326 "2014-06-07T22:38:50Z")
**Posts on this page:** 20
**Page:** 1
### Author:  [@Discourse](https://meta.discourse.org/u/Discourse)
#### Post date: [June 7, 2014, 10:38pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/1 "2014-06-07T22:38:50Z")
You just installed Discourse via [the install guide](https://github.com/discourse/discourse/blob/main/docs/INSTALL.md), 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!
## Try the doctor 👩⚕️
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? But wait! If your password has anything other than numbers and letters, you might be better off editing your `app.yml` with `nano` or your favorite editor.
You can also double check the settings in your `containers/app.yml` file. A valid email section looks like this:
```yaml
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
- no leading `#` characters
- single quotes around the developer email field
- password does not include `#`, `"`, `'`, `%`, `]` or other special characters (a `#` in a YAML value can be misinterpreted as a comment; if you must use special characters, wrap the value in double quotes, e.g. `DISCOURSE_SMTP_PASSWORD: "#pass#ord"`)
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
```
### Well, you don’t **always** need to rebuild
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:
```plaintext
cd /var/discourse
./launcher destroy app
./launcher start 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, first try port 2525, and if that fails, 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
```
less shared/standalone/log/rails/production.log
```
To page through the complete log, press space or type GG to jump to the end. Look closely for any email related messages or press /, type `email`, and hit enter to search.
## 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](https://woodpecker.co/blog/spf-dkim/), 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 exec 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:
```ruby
./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:
```yaml
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:
```bash
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’](https://meta.discourse.org/t/troubleshooting-email-on-a-new-discourse-install/16326/114) is extremely important in your first steps of email troubleshooting.
Port 465 (SMTP over SSL) uses implicit TLS. If you need to use port 465, add this to your `app.yml`:
```yaml
DISCOURSE_SMTP_PORT: 465
DISCOURSE_SMTP_FORCE_TLS: true
```
You may also need to try alternate ports such as [port 2525](https://pepipost.com/blog/25-465-587-2525-choose-the-right-smtp-port/) 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.
> [@meglio](#):
>
> 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](https://www.ndchost.com/wiki/mail/test-smtp-auth-telnet)
> 2. How to send an email from telnet:
> [http://askubuntu.com/a/493548/47475](http://askubuntu.com/a/493548/47475)
>
> Followed these two and successfully sent an email with Mandrill SMTP.
See also [Test SMTP authentication and StartTLS - Sysadmins of the North](https://www.saotn.org/test-smtp-authentication-starttls/).
## Office 365 Tweaks
If you’re using Office 365, be sure to include these (the first line is what you are likely missing):
```yaml
DISCOURSE_SMTP_AUTHENTICATION: login
DISCOURSE_SMTP_ENABLE_START_TLS: true
DISCOURSE_SMTP_PORT: 587
```
and set the correct value for `DISCOURSE_NOTIFICATION_EMAIL` (which is likely different from your forum hostname).
## TLS and SSL issues
By default, Discourse uses STARTTLS to encrypt its connection to the email server. Some email servers (increasingly rare nowadays) don’t support this or aren’t configured to use it, so it can be disabled by adding this line:
```yaml
DISCOURSE_SMTP_ENABLE_START_TLS: false #default: true
```
Other email servers might support STARTTLS, but use a self-signed certificate. This is uncommon and can be enabled with:
```yaml
DISCOURSE_SMTP_OPENSSL_VERIFY_MODE: none #default: peer
```
## 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.)
```bash
getent hosts your.smtp.server
```
On success, it will look like this or will be blank on failure.
```bash
# 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.
```bash
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](https://netcorecloud.com/tutorials/smtp-connection-from-command-line/)
### 4. Use your found working connection settings with Discourse.
🚀
### Bonus: show Discourse IP from inside docker container
( `ifconfig` , `ip` etc. are not installed inside the container.)
```bash
hostname -I
```
Result like:
```bash
172.17.0.2
```
> Last edited by @philo 2025-03-04T18:51:41Z
>
> > **Check document**
> >
> > Perform check on document:
---
### Author:  [@jeanas](https://meta.discourse.org/u/jeanas)
#### Post date: [September 6, 2023, 1:08pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/522 "2023-09-06T13:08:56Z")
> [@Discourse](#):
>
> 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:
Is this up to date information? It did not work for me; I had to rebuild the app after changing the SMTP port.
---
### Author:  [@jaileleu](https://meta.discourse.org/u/jaileleu)
#### Post date: [November 29, 2023, 11:36pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/530 "2023-11-29T23:36:17Z")
If `discourse-doctor` tells the connection to port 587 failed, but the `openssl s_client -connect your.smtp.server:587 -starttls smtp` works fine, try this, both commands should takes the same amount of time:
```plaintext
time openssl s_client -starttls smtp -connect your.smtp.server:587 /dev/null
docker run --rm discourse/base:2.0.20231023-1945 bash -c 'time openssl s_client -starttls smtp -connect your.smtp.server:587 /dev/null
```
If docker version is far longer, you may have a wrong configuration in your `/etc/docker/daemon.json` file. You may try to put google nameserver in first place :
```plaintext
{
"dns": ["8.8.8.8", "ww.xx.yy.zz", "ww.xx.yy.za"]
}
```
---
### Author:  [@lunasol](https://meta.discourse.org/u/lunasol)
#### Post date: [January 10, 2024, 12:04pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/531 "2024-01-10T12:04:04Z")
port 2525 works for mailjet.
587 failed.
---
### Author:  [@pfaffman](https://meta.discourse.org/u/pfaffman)
#### Post date: [January 10, 2024, 12:58pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/532 "2024-01-10T12:58:49Z")
I edited the OP to suggest using port 2525. It’s your hosting service that blocks the port. Because of that, many mail services also support 2525.
---
### Author:  [@wal](https://meta.discourse.org/u/wal)
#### Post date: [July 23, 2024, 8:50pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/533 "2024-07-23T20:50:43Z")
hey, just wanted to add a note about this;
> 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.
I signed up this week (July 2024) and so far, its working without having to add a credit card, using the base free tier. Based on what I have seen in old forum threads, it seems like they have been flip-flopping on this policy, and their free tiers usage and limitations, perhaps
---
### Author:  [@pfaffman](https://meta.discourse.org/u/pfaffman)
#### Post date: [July 23, 2024, 8:51pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/534 "2024-07-23T20:51:44Z")
> [@wal](#):
>
> I signed up this week (July 2024) and so far, its working without having to add a credit card, using the base free tie
Wow. That’s crazy and very different from how things have been for as long as I can remember.
It’s been very hard for people to figure out how to get changed to the pay-as-you-go plan and not sign up for some fairly expensive monthly plan.
Have you sent to users other than yourself?
---
### Author:  [@wal](https://meta.discourse.org/u/wal)
#### Post date: [July 24, 2024, 12:33pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/535 "2024-07-24T12:33:26Z")
Yes, I have sent to users, and its working. Only hitch, is that for some reason AOL email addresses are blocking my emails, but I dont think that is MailGun’s fault. I am just as surprised as you 🙂
update: seems that the reason some emails are getting blocked, is because the IP used to send the free emails from MailGun is shared, so it has been reported as “Spam” by some email platforms such as AOL, Yahoo Mail, and others. Seems like everyone who is not using Gmail is seeing bounced or rejected email delivery.
---
### Author:  [@Fluffy\_Circus](https://meta.discourse.org/u/Fluffy_Circus)
#### Post date: [August 30, 2024, 6:13pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/537 "2024-08-30T18:13:11Z")
Can you please explain how to check the settings in our `containers/app.yml` file? Us noobs don’t know how to do these things without explicit instruction. lol
---
### Author:  [@pfaffman](https://meta.discourse.org/u/pfaffman)
#### Post date: [August 30, 2024, 6:30pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/538 "2024-08-30T18:30:34Z")
If you don’t know how to use a tool like nano, then run discourse-setup again. After it’s saved the changes, you can control-c and then
```
./launcher destroy app;./launcher start app
```
---
### Author:  [@Fluffy\_Circus](https://meta.discourse.org/u/Fluffy_Circus)
#### Post date: [August 31, 2024, 12:15pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/539 "2024-08-31T12:15:57Z")
> [@Fluffy\_Circus](#):
>
> check the settings in our `containers/app.yml` file?
ok, but how do I check the settings in my `containers/app.yml` file so I can look at the email section and verify the data is correct?
---
### Author:  [@pfaffman](https://meta.discourse.org/u/pfaffman)
#### Post date: [August 31, 2024, 12:18pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/540 "2024-08-31T12:18:16Z")
If you don’t like my answer you can Google “nano”.
Arguably the OP should say something about nano, though, as I said, if you don’t know what it is then just running discourse-setup again is what to do, as it reads the values in the file and you can’t screw up the formatting
---
### Author:  [@Fluffy\_Circus](https://meta.discourse.org/u/Fluffy_Circus)
#### Post date: [August 31, 2024, 12:25pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/541 "2024-08-31T12:25:42Z")
Oh I see what you mean now. When you run the destroy then start commands, it displays the data I need once it’s complete. My apologies! 🙂
---
### Author:  [@Fluffy\_Circus](https://meta.discourse.org/u/Fluffy_Circus)
#### Post date: [August 31, 2024, 3:14pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/542 "2024-08-31T15:14:24Z")
I ran the doctor and got an error that says SMTPAuthenticationError. The doctor then says this is not a common error and they have no suggestions on how to fix it. If this happens, make sure to double check your SMTP username and password, as the Discourse setup process doesn’t tell you if it’s wrong, it just doesn’t work (doesn’t send emails) and leaves you stumped. Some things I did that helped was SSH into my server using Ubuntu instead of LISH (because I am using Linode) because LISH is terribly buggy and doesn’t support copy/paste. I then redid the setup process and copy/pasted everything this time instead of typing out 100 character passwords, lol. Anyways, I hope this helps some of my fellow noobs out there!
---
### Author:  [@pfaffman](https://meta.discourse.org/u/pfaffman)
#### Post date: [August 31, 2024, 5:16pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/543 "2024-08-31T17:16:15Z")
> [@Fluffy\_Circus](#):
>
> SMTPAuthenticationError
Your username or password is bad.
> [@Fluffy\_Circus](#):
>
> The doctor then says this is not a common error and they have no suggestions on how to fix it.
Not sure why I didn’t manage to fix that, but the error is pretty self explanatory.
It could be that you copy/pasted it wrong. It could be that it has characters that need to be escaped.
---
### Author:  [@Bryan\_Bai](https://meta.discourse.org/u/Bryan_Bai)
#### Post date: [September 3, 2024, 8:39am UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/544 "2024-09-03T08:39:03Z")
I use Brevo as my notification email sender, yet every single notification sent was rejected due to an error occurrence. I found a message in Brevo stating that “Sending has been rejected because the sender you used is not valid. Validate your sender or authenticate your domain”. Because of this, my forum cannot function at all. I’m wondering how to troubleshoot this - what kind of sender do I need? Thanks a lot!!!
---
### Author:  [@Architect](https://meta.discourse.org/u/Architect)
#### Post date: [September 3, 2024, 4:24pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/545 "2024-09-03T16:24:44Z")
> [@Bryan\_Bai](#):
>
> Validate your sender or authenticate your domain
For sender address can be set to mail subdomain you are using to send mail, such as mail@domain\_address.
To authenticate subdomain + sender there are a few steps for that they have a guide here:
> **[Comply with Gmail, Yahoo, and Microsoft's requirements for email senders](https://help.brevo.com/hc/en-us/articles/14925263522578-Comply-with-Gmail-Yahoo-and-Microsoft-s-requirements-for-email-senders)**
>
> 💡 Need help setting up your requirements?
> Hire a Brevo Certified Expert to ensure your setup is smooth and compliant with Gmail, Yahoo, and Microsoft's requirements!
> Hire a Brevo Expert
>
>
> Since Feb...
> **[Authenticate your domain with Brevo (Brevo code, DKIM, DMARC)](https://help.brevo.com/hc/en-us/articles/12163873383186-Authenticate-your-domain-with-Brevo-Brevo-code-DKIM-DMARC)**
>
> ❗️ Important
> Domain authentication is mandatory as part of Gmail,
> Yahoo,
> and Microsoft's requirements for email senders. To learn more, check
> our
> dedicated article
> ...
> **[Create a new sender (From name and From email)](https://help.brevo.com/hc/en-us/articles/208836149-Create-a-new-sender-From-name-and-From-email?source=search)**
>
> Choosing the right sender for your emails is an important step. The sender name and address appear in the inboxes of your recipients, helping them recognize who you are and trust your messages.You ...
---
### Author:  [@Guilllouv](https://meta.discourse.org/u/Guilllouv)
#### Post date: [October 11, 2024, 8:12am UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/546 "2024-10-11T08:12:13Z")
Hi Discourse people!
I have fought for several days with setting the emails parameters with port 465, and the solution is not here nor in any post I read on the forum (and I have really dug).
Of course it is a matter of what _your_ mail server accepts. In my case, **only** 465 **over TLS**.
The _two_ required config lines to add in `app.yml` are:
```plaintext
DISCOURSE_SMTP_FORCE_TLS: true
DISCOURSE_SMTP_ENABLE_START_TLS: false
```
###### Some details
Default settings resulted in a `Net::ReadTimeout` error when trying a test email with `discourse-doctor`. Sending test emails from within the container work fine with e.g. `curl`, exactly as in this post which led me to half of the solution: [Cannot send email - problem with port 465 - #10 by schungx](https://meta.discourse.org/t/cannot-send-email-problem-with-port-465/246004/10)
I could only find out about the second setting after looking at `app.yml` content and modifying this parameter. I have the feeling that most programs (eg. Thunderbird) implicitly set the correct protocol when selecting port 465, so maybe Discourse should? This seems to be really standard, also as highlighted here:
> [@Sending email failed with SMTPS port 465](https://meta.discourse.org/t/sending-email-failed-with-smtps-port-465/65787/14):
>
> And upon reading the [actual RFC from 2018](https://www.rfc-editor.org/rfc/rfc8314#section-3.3) it’s clear – it’s not that STARTTLS is the way forward, it’s that SMTPS is _not_ the way forward, and implicit TLS over port 465 (or 587) is what administrators should choose going forward.
>
> Supporting TLS over 465 should not be classed (and likely de-prioritized) as “maintaining backwards compatibility” or any similar notion.
([link](https://meta.discourse.org/t/sending-email-failed-with-smtps-port-465/65787/14) to full post)
So I would really vouch for updating the section of this guide about port 465 or make `discourse-setup` automatically choose the best setting.
---
### Author:  [@Nikolai\_Patrushev](https://meta.discourse.org/u/Nikolai_Patrushev)
#### Post date: [October 27, 2024, 11:45pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/547 "2024-10-27T23:45:20Z")
Normally i dont comment on stuff, but that was actually helpfull!
Thanks man, the maintainer of the discourse absolutly should include this setting in the default config, i mean it was tedious to setup theirs software, still i have nothing to crictise accept that in such big project some information is not fast available and somebody should “deep into”.
**OK works for me!**
---
### Author:  [@tobiaseigen](https://meta.discourse.org/u/tobiaseigen)
#### Post date: [February 8, 2025, 5:18pm UTC](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326/548 "2025-02-08T17:18:03Z")
A post was merged into an existing topic: [Use of % in SMTP Password for discourse-setup](https://meta.discourse.org/t/use-of-in-smtp-password-for-discourse-setup/106434/15)
[Next page](https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install/16326.md?page=2)