Configuring Email Notifications in Jenkins

Once you have many jobs and pipelines, nobody can keep watching the dashboard to see which build passed and which failed. Some builds take a long time: compiling a big application, building a Docker image, deploying to a cluster. You want Jenkins to tell you the result, wherever you are, and especially when something breaks.

The simplest way is email. Jenkins sends a message when a build succeeds or fails, with a link and the log attached.

Two plugins handle email, and both come with the suggested plugins:

Step 1: get SMTP details and an app password

Jenkins does not send email itself. It hands the message to an SMTP server. In a company, the IT team gives you the SMTP host, port and an account. For practice, Gmail works:

Google does not let apps like Jenkins sign in with your normal password. You create an app password instead:

1. Turn on 2-Step Verification for the Google account. App passwords only exist for accounts with 2-Step Verification.
2. In your Google Account, search for App passwords.
3. Enter a name such as Jenkins application and click Create.
4. Google shows a 16-character password once. Copy it.

Step 2: configure Extended E-mail Notification

Go to Manage Jenkins > System and scroll to Extended E-mail Notification.

SMTP server and port, with the Advanced section open. The Credentials drop-down is still empty here; select the app password credential in it once you have created it.

Click Save.

To test before writing any pipeline, the E-mail Notification section (Mailer plugin) further down has Test configuration by sending test e-mail. Fill in the same server, SSL, port and login under its Advanced settings, enter a recipient, and click Test configuration. "Email was successfully sent" means the SMTP part works.

Step 3: send email from a pipeline

Create a new pipeline job sample-pipeline with the description Sample email notification:

pipeline {
    agent any

    tools {
        maven "maven"
    }

    stages {
        stage('Git Clone') {
            steps {
                echo 'Cloning Project from Git'
            }
        }

        stage('Maven Build') {
            steps {
                echo 'Building Project with Maven'
            }
        }

        stage('Deploy') {
            steps {
                echo 'Deploying Application'
            }
        }
    }

    post {
        success {
            emailext(
                subject: "Build Successful: ${currentBuild.fullDisplayName}",
                body: "The build ${currentBuild.fullDisplayName} completed successfully.",
                to: "your-team@example.com",
                attachLog: true
            )
        }

        failure {
            emailext(
                subject: "Build Failed: ${currentBuild.fullDisplayName}",
                body: "The build ${currentBuild.fullDisplayName} failed. Check the console: ${env.BUILD_URL}console",
                to: "your-team@example.com",
                attachLog: true
            )
        }
    }
}

Replace your-team@example.com with the real recipient. Separate several addresses with commas.

The post section

post sits after stages, inside pipeline. It runs once all stages are done, and its blocks decide what runs for which result:

fixed and regression are worth knowing: many teams email only on those, so people are not flooded with "still green" messages.

The emailext parameters

currentBuild.fullDisplayName is the job name plus build number, for example sample-pipeline #1. env.BUILD_URL is the link to the build, which only works if the Jenkins URL in Manage Jenkins > System is correct.

You do not need to remember all this: the Snippet Generator has an emailext: Extended Email step that writes the call for you.

Step 4: run it

Save and click Build Now. The stage view shows the three stages and then Post Actions. A few seconds later, an email like this arrives:

Subject: Build Successful: sample-pipeline #1
The build sample-pipeline #1 completed successfully.
Attachment: build.log

To see the failure email, add error 'Simulated failure' to the Deploy stage and run again.

When no email arrives

Check the end of the console output first. The plugin logs what it did:

Try It Yourself

1. Create a Gmail app password, store it as the smtp-cred credential, and send a test email from E-mail Notification.
2. Build sample-pipeline and check that the success email arrives with build.log attached.
3. Make the Deploy stage fail and confirm you get the failure email instead.
4. Change success to fixed and failure to regression, then run a failing build followed by a passing one. Which builds send email?
5. Add the same post block to First-pipeline from the earlier lessons.

Official references

• Email Extension plugin
• Jenkins Pipeline Syntax: post
• Google Account Help: Sign in with app passwords

Written By: Shramik Masti