Skip to main content
In this tutorial, we’ll replace Jenkins’s built-in email notifications with the powerful Email Extension Plugin. You’ll learn how to install the plugin, configure global SMTP settings, and customize notifications for your Freestyle jobs—including attachments and conditional triggers.

​
1. Install the Email Extension Plugin

  1. Go to Manage Jenkins → Plugin Manager → Available.
  2. Search for Email Extension Plugin and click Install without restart.
  3. When installation completes, restart Jenkins.
The image shows the Jenkins plugin management interface, specifically the "Available plugins" section, with options to install email-related plugins.
Refer to the official Email Extension plugin documentation for advanced examples and template syntax.
The image shows a webpage for the Jenkins Email Extension plugin, detailing its documentation, version information, and usage instructions. It includes links for further resources and installation statistics.
Once Jenkins restarts, log in and confirm the plugin appears under Installed.
The image shows a Jenkins interface displaying the download progress of plugins, with details about the status of various plugins and options for restarting Jenkins.

​
2. Configure Global Email Settings

Navigate to Manage Jenkins → Configure System and scroll to Extended E-mail Notification. Set up your SMTP details:
SettingValueDescription
SMTP Serversmtp.gmail.comGmail SMTP host
SMTP Port465SSL port
Use SSL☑️Secure connection
CredentialsAdd Gmail Username/PasswordUse an app-specific password
Default Content Typetext/htmlHTML format for email body
Attachment Size Limit(leave blank)Unlimited by default
  1. Add Credentials
    Click Add → Jenkins and select Username with password.
Generate an app-specific password in your Google Account under Security → App passwords.
The image shows a Jenkins interface for adding credentials, with fields for domain, kind, scope, username, and password.
  1. Select the new credentials and enable Use SSL.
The image shows a Jenkins system configuration page for setting up an SMTP server with fields for server details, credentials, and security options like SSL, TLS, and OAuth 2.0.
  1. Default List-ID Header
    Optionally specify a List-ID to group your emails.
The image shows a Jenkins system configuration page with options for setting a List-ID header for emails. It includes fields for default content type and examples of List-ID formats.
  1. Default Subject & Body
    Use tokens like ${PROJECT_NAME}, ${BUILD_NUMBER}, and ${BUILD_STATUS}.
The image shows a Jenkins system configuration page, specifically for setting up email notifications with fields for default subject, content, and scripts.
  1. Default Triggers
    Enable Failure – Any, and add others (e.g., Unstable, Always) as needed.
TriggerSends When
Failure – AnyAny build failure
UnstableBuilds with test failures
AlwaysEvery build, regardless of outcome
The image shows a Jenkins system configuration page with various build status options, such as "Failure - Any" and "Test Improvement," with checkboxes for selection. There are buttons for saving and applying changes at the bottom.
Click Apply and Save to persist.

​
3. Configure a Freestyle Job

Open your Freestyle project (e.g., npm-version-test) and click Configure.
  1. Remove any existing E-mail Notification.
  2. Under Post-build Actions, select Add post-build action → Editable Email Notification.
  3. Add a Shell Build Step to simulate failure: 
    echo "Updating job config using Jenkins CLI"
node -v
npm -v
exit 1
The exit 1 command will force the build to fail to trigger the failure notification.
  1. Project Recipient List
    Leave blank to use global defaults or specify an address (e.g., [email protected]).
The image shows a Jenkins configuration screen for post-build actions, specifically focusing on email notification settings. It includes options for editable email notifications, project recipient list, and reply-to list.
  1. Leave Default Subject and Default Content inherited from global settings.
  2. Click Apply and Save.

​
3.1 Trigger a Build Without Recipients

Run the job to see: 
Email was triggered for trigger: Failure - Any  
Sending email for trigger: Failure - Any  
An attempt to send an e-mail to empty list of recipients, ignored.
By default, the plugin only mails Developers, not your recipient list.

​
4. Add Recipients and Rerun

  1. In Editable Email Notification, expand Advanced Settings.
  2. Under Default Recipients, add your email or check Send to Recipient List for each trigger.
The image shows a Jenkins system configuration page with fields for email settings, including default recipients and other email-related options. The interface has a dark theme with options to save or apply changes.
Save and rebuild:
The image shows a Jenkins configuration screen for a job named "npm-version-test," focusing on the "Post-build Actions" section with options to send notifications to developers and a recipient list.
Now the console shows: 
Email was triggered for: Failure - Any  
Sending email for trigger: Failure - Any  
Sending email to: [email protected]

​
5. Verify in Your Inbox

You should receive a notification with your default HTML template:
The image shows a Gmail inbox with an email notification about a Jenkins build failure. The email subject indicates "npm-version-test - Build #13 - Still Failing" with a link to view the console output.

​
6. Attach the Build Log

To include the build log in your notification:
  1. Under Editable Email Notification → Advanced Settings, enable Attach Build Log and optionally Compress Build Log.
  2. Save and rerun the job.
The image shows a Jenkins configuration screen for a job named "npm-version-test," displaying options for post-build actions and script settings.
The next email will include build.log as an attachment:
The image shows a Gmail inbox with an email about a failed Jenkins build, labeled "npm-version-test - Build #14 - Still Failing!" It includes a link to view the console output and an attachment named "build.log."
You’ve now set up the Jenkins Email Extension Plugin for Freestyle jobs—covering installation, global SMTP configuration, project-level notifications, triggers, and attachments.

Watch Video