Troubleshooting Email Notifications in Jenkins: Comprehensive Guide

In a previous post, I walked you through the process of setting up email notifications in Jenkins. If you haven't read it yet, I recommend checking it out here to get started with the basics. While working on that guide, I encountered a few challenges myself. Inspired by these issues and the common problems others face, I decided to create this follow-up post to cover all possible issues that can arise during email notification setup and how to solve them.

This guide is a deep dive into troubleshooting email notifications in Jenkins, covering everything from basic misconfigurations to advanced debugging techniques. Let’s ensure your notification system is reliable and ready to keep your team informed!

Introduction

Email notifications are an essential feature in Jenkins, keeping teams updated on build statuses and other events. However, they’re also one of the most commonly misconfigured features due to the interplay of plugins, SMTP settings, and network restrictions.

This guide provides solutions to common issues and advanced troubleshooting techniques, ensuring your email notifications work seamlessly.

1. Link to the Basic Guide

If you're new to configuring email notifications in Jenkins, I recommend starting with my earlier post, Setting Up Notifications in Jenkins: A Step-by-Step Guide. It covers prerequisites, installation steps, and a basic setup guide.

In this post, we'll build on that foundation by addressing issues you might encounter during or after the setup.

2. Common Problems and Their Symptoms

Here are some common issues you might face:

1. Emails are not being sent from Jenkins despite a correct configuration.
2. Authentication failures when connecting to the SMTP server.
3. Emails are sent but not received by the intended recipients.
4. Empty emails or incorrectly formatted content.
5. Timeout errors when connecting to the SMTP server.

2.1 Troubleshooting SMTP Configuration Issues

Incorrect SMTP Server Settings

Symptoms:

• Errors such as "Could not connect to SMTP server".

Solutions:

1. Double-check the SMTP server address and port.
   • For Gmail: smtp.gmail.com, Port: 587 (TLS) or 465 (SSL).
   • For Outlook: smtp.office365.com, Port: 587.
   • For SendGrid: smtp.sendgrid.net, Port: 465 (Use SSL)
2. Ensure the protocol matches the port (TLS vs. SSL).
3. Validate credentials by logging into the email account directly. For SendGrid, use Username: apikey and Password: <SENDGRID_API_KEY> itself.
4. Use the "Test configuration by sending test e-mail" feature in Jenkins.
5. Check that you configured E-mail Notification and Extended E-mail Notification too in Jenkins System Settings.

2.2 Authentication Errors

Symptoms:

• Messages like "Authentication failed" or "Invalid username/password".

Solutions:

1. Generate an App Password for services like Gmail.
   • Follow this guide to create one.
2. Ensure "Allow less secure apps" is enabled if required.
3. If using an enterprise SMTP server, confirm the required authentication method (e.g., Basic, OAuth2).
4. For SendGrid, check that your domain is Authenticated.

2.3 Firewall or Network Restrictions

Symptoms:

• SMTP server unreachable or connection timeouts.

Solutions:

1. Verify that your Jenkins server has internet access and can reach the SMTP server.
2. Check your organization's firewall rules to allow outgoing SMTP traffic.

Use the telnet or nc command to test connectivity:

telnet smtp.gmail.com 587  

2.4 Debugging Email Content and Delivery

Empty or Missing Emails

Symptoms:

• Recipients receive emails without content or subject.

Solutions:

1. Ensure the Default Subject and Default Content fields in the email configuration are set.
2. Add dynamic variables like ${BUILD_STATUS} to include build status in the email.
3. Verify the Editable Email Notification settings in the "Post-build Actions."
4. For more information about sending the email process, you can check the checkbox called Enable Debug Mode in the Extended E-mail Notification

2.5 Email Formatting Issues

Symptoms:

• Recipients receive poorly formatted emails or plain text instead of HTML.

Solutions:

1. Enable the "Use HTML" option in the email configuration.
2. Use proper HTML templates for well-structured emails.

3. Testing Email Configuration

To validate your setup:

1. Navigate to Manage Jenkins > Configure System > Extended E-mail Notification.
2. Click Test configuration by sending test e-mail.
3. Monitor the Jenkins logs for the following:
   • Success: "Mail sent successfully."
   • Failure: Check the error logs for detailed messages.

4. Advanced Debugging Techniques

Enabling Debug Logs in Jenkins

1. Go to Manage Jenkins > System Log.
2. Add a new logger for the email plugin, setting the log level to ALL for the following:
   • hudson.tasks.MailSender
   • hudson.plugins.emailext

Verifying Connection to the SMTP Server

1. Review the response for connection errors.

Use the curl command to test SMTP connectivity:

curl -v smtps://smtp.gmail.com:465 --ssl  

5. FAQ and Common Scenarios

Q1: Why are emails delayed?

• Delays are often caused by the SMTP server's queue. Contact your provider for details.

Q2: Can I use a custom email domain?

• Yes, ensure you configure the correct SMTP settings for your domain.

Q3: Why does the test email work, but build notifications fail?

• Ensure the "Post-build Actions" are properly configured in the job settings.

Conclusion

Email notifications are a crucial part of Jenkins' functionality, but they can also be one of the most challenging features to configure. With the solutions outlined in this guide, you should be able to resolve most issues and ensure a smooth notification experience.

If you haven’t already, don’t forget to check out my initial guide on setting up email notifications in Jenkins. Together, these resources will help you build a reliable and efficient notification system.