Send Email Notification From Jenkins

Last updated: November 6, 2023

Reviewed by: Luis Javier Peris

1. Overview

In this tutorial, we’ll see two different ways to send email notifications from Jenkins. They can be very useful when we want to be notified immediately about issues in our pipeline.

2. Environment Setup

Firstly, we’ll set up our environment. Let’s use Docker Compose because it allows us to do it fairly simply.

For this tutorial, we need a container that runs the Jenkins Docker image. In addition, we’ll use MailHog to test the email-sending functionality.

2.1. Docker-Compose

Let’s create the docker-compose.yaml file which describes our environment:

version: '3.7'

services:

    mailhog:
      image: mailhog/mailhog:v1.0.1
      container_name: mailhog
      networks:
        - jenkins
      ports:
        - 1025:1025
        - 8025:8025

    jenkins:
      image: jenkins/jenkins:2.361.1-lts-jdk11
      container_name: jenkins
      networks:
        - jenkins
      ports:
        - 8080:8080
        - 50000:50000

networks:
  jenkins:

There are a few important details here that we need to know about. Firstly, let’s see the network configuration. Both of the containers use the same network. It’s important because otherwise, they wouldn’t be able to communicate with each other.

Secondly, let’s take a look at the ports of these containers. MailHog uses port 1025 for the SMTP server. Therefore, we need to use this port from Jenkins to send the emails. The other port can be used to access a user interface from our browser. Jenkins provides its user interface on port 8080.

2.2. Running the Containers

Let’s start the Docker containers:

$ docker-compose up -d

Now we can access them at the ports described above. Let’s start with MailHog and open http://localhost:8025/ in our browser. We should see this interface:

mailhog interface at start

The emails will appear in a list as soon as we send them from Jenkins.

Now, let’s visit http://localhost:8080/ and open the Jenkins UI as well.

2.3. Jenkins Setup

The Jenkins container takes some time to start and it shows a loading indicator on the UI. After that, we see a password prompt where we enter the generated admin password.

On the next screen, we should install all the suggested plugins and wait for it to finish. Then, we can create a new user, but it’s not necessary. Let’s skip it and continue as admin. Similarly, on the Instance Configuration page, we can just click save and finish. Now, we can use all the necessary functionalities.

3. Built-in Solution

Jenkins provides a built-in solution for sending emails. We can configure this in the Manage Jenkins menu under the Configure System option.

Let’s scroll down to the bottom of the page and take a look at the E-mail Notification section:

jenkins configure email notification

Here, we need to configure the SMTP details. This should be the address and port of the MailHog container. The SMTP server can be simply “mailHog” because the two containers can access each other. The port can be configured under the Advanced settings section and it should be set to 1025 for this tutorial.

We can even test this configuration after checking the checkbox and providing an email address. Let’s apply the configuration and send a test email. We can verify this on the MailHog UI, a new email appeared in the list.

3.1. Usage in a Job

We can send test emails from the settings, but in real-world scenarios, we want to receive emails about relevant events. For example, we might want to be notified when a build fails. Let’s create a simple job for this that only prints a message.

Firstly, we’ll select New Item from the left-side menu and create a Freestyle project with the name “Email Test Job”.

When we create this job we are redirected to the configuration screen. Let’s scroll down to Build Steps and add an Execute shell step. Let’s add a simple script here:

echo "Test job for sending emails."

Under this section, we can add some actions that will be executed after our job. We’ll create an E-mail Notification post-build action. Let’s set an email address as the recipient and save the job configuration:

jenkins email test job configuration

Let’s save the configuration, then click Build Now to run this job and check the result. We see our message in the console output, but we didn’t receive any emails via MailHog. It’s the expected behavior in this case.

This email notification is triggered only for certain events. An e-mail will be sent when a build fails, becomes unstable, or returns to stable. This means we should create a situation where one of these events happens. For example, we can create a failing build by modifying the executed shell script. Let’s exit with a non-zero exit code from this script. This makes Jenkins treat it as a failed build:

echo "Test job for sending emails."
exit 1

Let’s run the job again and check the result. This execution is marked as failed in Jenkins and we also received an email from MailHog. The email subject is “Build failed in Jenkins: Email Test Job #2”. We can see the details in the body.

Let’s remove the exit command from the script and rerun the job. This time, the build status is successful and we received an email again. The subject is “Jenkins build is back to normal: Email Test Job #3”. However, sometimes we need to be notified about more events and the email extension plugin can help with that.

4. Email Extension Plugin

We can use the Email Extension plugin as well to send emails from Jenkins. Most importantly, it supports more events than the built-in solution.

Let’s open the Configure System menu. We should see a section titled Extended E-mail Notification.

Let’s use the same SMTP configuration values as we used in the previous example. The SMTP server should be “mailhog” with the 1025 port. We can customize this further as we like, but this is enough for our example. Unfortunately, we can’t test the configuration for this plugin. Let’s try it in the previously used job.

4.1. Usage in a Job

We’ll change the configuration of the “Email Test Job” that we used previously. Let’s remove the previous post-build action and add a new one named Editable Email Notification.

Firstly, let’s put an email address into the Project Recipients List field. This address will receive the notifications. By default, this plugin sends emails only when a build fails. We should change it to see all the events it supports. Let’s open the advanced settings and scroll down to Triggers. We can already see the trigger that sends an email to the developers any time a build fails:

jenkins email extension failure trigger

Let’s delete this and replace it with a trigger of type Always. We can find many other types of triggers here, too. There are also a lot of other configuration options. For example, we can set who receives the notifications, what’s the subject and content of the emails or even add attachments. But, we can keep the default settings for this example and save the job:

jenkins email extension always trigger

Let’s run it and take a look at our inbox in MailHog. We received an email about the successful build. Let’s change the shell script of the job again and exit with an error code:

echo "Test job for sending emails."
exit 1

If we run the job again we get an email notification about the failure. Let’s remove the exit command from the script and test it one more time. As a result, we get an email that says the build is fixed.

5. Conclusion

In this article, we saw two different approaches to sending email notifications from Jenkins. Firstly, we used the built-in solution which can send emails when a build fails or becomes stable again. Secondly, we used the Email Extension plugin which can be used when we need more control over the events that trigger the notifications.

Comments are open for 30 days after publishing a post. For any issues past this date, use the Contact form on the site.