Send Email Notifications from Jenkins Build Pipelines (2026)

Jenkins is surprisingly bad at sending emails, and it’s not because the underlying SMTP libraries are complex. It’s because the default configuration is intentionally minimal and relies on you to bridge the gap between a simple notification trigger and the actual SMTP server that handles delivery.

Here’s a Jenkins pipeline that sends an email on failure:

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
                // Simulate a failure for demonstration
                script {
                    error("Build failed!")
                }
            }
        }
    }
    post {
        failure {
            mail to: 'recipient@example.com',
                 subject: "Build failed: ${env.JOB_NAME} - ${env.BUILD_NUMBER}",
                 body: "Build ${env.BUILD_NUMBER} for job ${env.JOB_NAME} failed. See ${env.BUILD_URL} for details."
        }
    }
}

When this pipeline runs and the Build stage fails, Jenkins will attempt to send an email. But if you haven’t configured Jenkins’s Global Mailer settings, this email will disappear into the ether, and you’ll likely see a cryptic "Error sending email" message in the Jenkins system logs.

The core problem is that Jenkins, by default, doesn’t know how to talk to an SMTP server. It’s like having a phone but no phone number or dialing instructions. You need to tell it:

• Where to send the email (SMTP server address and port).
• How to authenticate with that server (username and password).
• If the server uses encryption (SSL/TLS).
• Which address to send from (the "sender" address).

To do this, you navigate to Manage Jenkins -> Configure System. Scroll down to the Extended E-mail Notification section. This is where you configure the global settings for email sending, which the mail step in your pipeline then uses.

SMTP Server Configuration:

• SMTP server: This is the hostname of your mail server (e.g., smtp.gmail.com for Gmail, mail.yourcompany.com for an internal server).
• SMTP Port: The standard port for unencrypted SMTP is 25. For SSL/TLS, it’s typically 465 or 587.
• Use SMTP Authentication: Check this box if your mail server requires a username and password.
• Username: The email address you use to log into your SMTP server.
• Password: The password for that username. Jenkins stores this securely.
• Use SSL/TLS: Check this if your server requires SSL/TLS encryption. This is highly recommended for security. For Gmail, you’ll likely use port 465 with SSL/TLS. For other servers, 587 with STARTTLS (which is often implied by "Use SSL/TLS" in Jenkins) might be used.
• Default user E-mail suffix: If your SMTP server uses a different domain for email addresses than your Jenkins server, you can specify it here (e.g., @yourcompany.com).

Default Settings:

• System Admin e-mail address: This is the "From" address that Jenkins will use for all outgoing emails. It should be a valid email address that your SMTP server can send from. Often, this is something like jenkins@yourcompany.com.

Once these settings are in place, Jenkins has the necessary credentials and routing information to connect to your SMTP server and send emails. The mail step in your pipeline then simply tells Jenkins what to send and who to send it to, leveraging the global configuration for the actual delivery mechanism.

The most surprising thing about Jenkins email is how infrequently the mail step itself is the problem; it’s almost always a misconfiguration in Configure System that causes emails to fail silently.

If you’ve correctly configured your SMTP server, authentication, and SSL/TLS settings, and your emails still aren’t sending, the next thing you’ll likely encounter is issues with your SMTP server’s firewall blocking Jenkins’s IP address.