This is an explanation guide discussing how admins can troubleshooting outgoing email from a Discourse site.
Required user level: Administrator
Discourse relies heavily on email for user notifications and account management tasks. If users are unable to receive emails from your Discourse site, this can lead to a variety of problems.
Summary
In this documentation, you will learn:
- How to check sent email logs
- Investigating skipped and bounced emails
- Common troubleshooting steps for email deliverability issues
- Key settings and where to find them
Checking Sent Emails
The first place to check when troubleshooting email issues is the Admin → Emails -> Sent page for your site (located at .../admin/email/sent).
The Email -> Sent page in Discourse is a valuable resource for administrators to monitor and troubleshoot the email functionality of their forum. This page provides a detailed log of all the emails that have been successfully sent from your Discourse instance.
Here’s all the information you can find about sent emails on this page:
- Sent At: How long as the email was sent.
- User: The user who received the email.
- To Address: The recipient’s email address.
- Email Type: The type of the email that was sent. It could be a digest, mailing list, user posted, user private message, etc.
- Reply Key: A unique identifier for each sent email. This key ensures that when a user replies to a notification email, Discourse can correctly match the reply to the appropriate post and user, so users to participate in forum discussions directly from their email.
- Post: The ID of the post that the email was generated from. Clicking on this ID will take you to the actual post in the forum.
-
SMTP Details: This field indicates the response received from the SMTP server after trying to send the email. A
250 2.0.0response means that the email was accepted for delivery by the first email server.
If a user reports they didn’t receive an email from Discourse, and Discourse shows a message of
250 2.0.0 Ok: queued as ...under theirPost & SMTP Detailsyou might want to have that user check their inbox again, along with their spam folder to see if they might have missed the emails somewhere, as this indicates those emails as having been successfully received. You could also recommend that the user contact the support team or IT department that manages their email server to see if they’re aware of anything that might be happening to the email after it was reported as delivered.
If an email does not appear on the Emails -> Sent page in Discourse, it means the email was not successfully sent from your Discourse instance.
Let’s take a look at some of the other pages we can use for email troubleshooting.
Investigating Skipped Emails
Located on your site’s .../admin/email/skipped page, the Skipped Emails page lists of all the emails that Discourse decided not to send for various reasons. Each skipped email will have a Skip Reason listed next to it, providing insight into why the email wasn’t sent.
The following information is available on this page about skipped emails:
- Time: The date and time when the email was supposed to be sent and was instead skipped.
- User: The user who was supposed to receive the email.
- To Address: The recipient’s email address.
-
Email Type: The type of the email that was skipped, such as
digest,mailing list,user posted,user private message, etc. - Skip Reason: The reason why the email was skipped. Common reasons include the user being active on the site, the user having already read a post, or the user exceeding the bounce score threshold.
Exceeded bounce_score_thresholdmean?
In Discourse, each time an email sent to a user’s email address bounces, the user’s ‘bounce score’ increases. The ‘bounce score’ is a measure of the number of failed delivery attempts for emails sent to a specific address.
The Exceeded bounce_score_threshold message in Discourse refers to the situation when a user’s ‘bounce score’ exceeds a certain limit, and is one of the most common reasons you would need to troubleshoot outgoing email from Discourse.
A bounced email is an email that couldn’t be delivered to the recipient and is returned to the sender. This can happen for a variety of reasons, and when it does, the sender’s email system receives a notification about the delivery problem.
There are two types of email bounces:
- Hard Bounce: This is a permanent delivery failure. It usually happens when the recipient’s email address is invalid or no longer in use. Other reasons could be that the domain name doesn’t exist or the recipient’s email server has completely blocked delivery.
- Soft Bounce: This is a temporary delivery issue. It could be due to the recipient’s mailbox being full, the email server being temporarily down or overloaded, or the email message being too large.
bounce_score_threshold?
Yes! See: Bounce Score Site Settings.
However, it’s important to make sure that any underlying issues with email deliverability are fully resolved before adjusting bounce score settings.
With that in mind, let’s discuss some of the other information we can see about bounced emails in Discourse.
Troubleshooting Bounced Emails
The bounced emails page is located at .../admin/email/bounced and provides a detailed overview of all bounced emails. Here’s what you can see on this page regarding bounced emails:
- Time: The date and time when the email was bounced.
- User: The user who was supposed to receive the email.
- To Address: The recipient’s email address.
- Email Type: The type of the email that was skipped. It could be a digest, mailing list, user posted, user private message, etc.
On the Bounced page, you can click the 
(i) icon to view additional details about a bounced email:
The Incoming Email Details window will have detailed information about the bounced email, and typically the Body section will provide an explanation as to why the email was bounced.
Here are a few reasons for why an email from Discourse might be getting bounced:
- Invalid Email Address: If the recipient’s email address is invalid, non-existent, or has been deleted, the email will bounce back.
- Full Mailbox: If the recipient’s mailbox is full and cannot accept new messages, the email will bounce back.
- Server Issues: If the recipient’s email server is down or temporarily unavailable, the email will bounce back. This is usually a temporary issue.
- Blocked Sender: The recipient’s email server might have blocked your Discourse email address, or might only allow incoming email from specific domains, typically due to email security policies.
- Aggressive Spam Filters: If the email content is flagged as spam by the recipient’s email server, the email can bounce back.
- Auto-Reply: Some auto-reply systems (like out-of-office replies) can cause a soft bounce.
In this situation, having the user whose emails are getting bounced reach out to their email service provider is the best option. The email service provide may be able to provide specific insights into why the emails are being blocked, rejected, etc. and may be able to adjust security settings or whitelist the Discourse email service. They might also be aware of ongoing email server maintenance, or other issues that would be causing emails to bounce.
If the user has control over their email services, and is using Microsoft Hosted Exchange or Google Workspace, we also have procedures for Bypassing spam for email from your CDCK-hosted site in Microsoft Hosted Exchange and Bypassing spam for email from your Discourse-hosted site in Google Workspace
You will need to either Reset the User’s Bounce Score, or if the issue was impacting multiple users you can Bulk Reset Bounce Scores for All Users. Once bounce scores have been reset, Discourse will resume attempting to deliver email to users who were exceeding their bounce_score_threshold.
Additional Steps
Email setup and troubleshooting can be complex due to the many variables involved.
Beyond looking through your site’s Admin → Email section to troubleshoot email, you may also want to go through our Email delivery configuration checklist if you’re still having trouble determining why emails are not getting delivered correctly from your Discourse site.
If your Discourse site was recently setup, we also have a guide on Troubleshooting email on a new Discourse install (self-hosted installs only).
Lastly, you can check the Discourse logs page by navigate to Admin > Logs (.../logs/) and looking for any errors you might see relating to email deliverability.
Last edited by @SaraDev 2024-07-26T20:23:54Z
Check document
Perform check on document:
