Please do not email me directly (Jenkins/plugin developers excluded). If you need help post on the mailing lists https://jenkins.io/mailing-lists/, stack overflow or if you have found a bug log an issue at https://issues.jenkins-ci.org (no support tickets please)

{jenkins-plugin-info:email-ext}

This plugin allows you to configure every aspect of email notifications. You can customize when an email is sent, who should receive it, and what the email says.

Build Status

Recipes

Additional recipes for email-ext can be found here.

General

This plugin extends Jenkins built in email notification functionality by giving you more control.  It provides customization of 3 areas.

Configuration

Global configuration

Before using email-ext on a project, you must configure some global settings.  Go to Jenkins System configuration page.  Manage Jenkins -> Configure System

The section titled Extended E-mail Notification is where you can configure global email-ext properties.  The properties here should match the settings for your smtp mail server.  This section is set up to mirror Jenkins own email Publisher Reporter (It's different extension point), however there are a few additions.  The inputs labeled Default Subject and Default Content, allow you to configure the email content on a global level.  The input labeled Default Recipients can be used to set a default list of email addresses for all projects using plugin (it can be overridden at the project level). This can be used to greatly simplify the configuration you need to do for all projects.

Project configuration

For a project to use the email-ext plugin, you need to enable it in the project configuration page.  Select the checkbox labeled "Editable Email Notification" in the  "Post-build Actions" section.

Basic Configuration

There are three fields that you can edit when the plugin is enabled.

Advanced configuration

To see the advanced configuration for the plugin, first click on Override Global setting checkbox, then click the "Advanced" button.  This section allows you to specify recipients for each type of email trigger as well as a pre-send script that can be used to modify the email just prior to sending. 

Pre-send Script

The pre-send script is a feature which allows you to write a script that can modify the MimeMessage object prior to sending. This would allow adding custom headers, modifying the body, etc. Predefined variables include:

Triggers

By default, the only trigger configured is the "Failure" trigger.  To add more triggers, select one from the dropdown, and it will be added to the list.  Once you have added a trigger, you have several options.  If you click "?" (question mark) next to a trigger, it will tell you what conditions must be met for it to send an email.

You can use Trigger Scripts in groovy to define before of after the build if the email must be send or not.

There are four objects added to the model for the script to use to interact with the build.

The last line in the script should resolve to a boolean true or false

Examples:

// this could be used to notify people that a new build is happening
build.previousBuild.result.toString().equals('FAILURE')
// only send am email if the build failed and 'mickeymouse' had a commit
build.result.toString().equals('FAILURE') && build.hasParticipant(User.get('mickeymouse'))
// only send an email if the word {{ERROR}} is found in build logs
build.logFile.text.readLines().any { it =~ /.*ERROR.*/ }

Email tokens

The email-ext plugin uses tokens to allow dynamic data to be inserted into recipient list, email subject line or body.   A token is a string that starts with a $ (dollar sign) and is terminated by whitespace.  When an email is triggered, any tokens in the subject or content fields will be replaced dynamically by the actual value that it represents.  Also, the "value" of a token can contain other tokens, that will themselves be replaced by actual content.  For instance, the $DEFAULT_SUBJECT token is replaced by the text (and other tokens) that is in the Default Subject field from the global configuration page.  Similarly, the $PROJECT_DEFAULT_SUBJECT token will be replaced by the value of the Default Subject field from the project configuration page

The email-ext plugin sets the email content fields with default values when you enable it for your project.  The Default Subject and Default Content fields on the project config page default to $DEFAULT_SUBJECT and $DEFAULT_CONTENT (respectively), so that it will automatically use the global configuration.  Similarly, the per-trigger content fields default to $PROJECT_DEFAULT_SUBJECT and $PROJECT_DEFAULT_CONTENT, so that they will automatically use the project's configuration.  Since the value of a token can contain other tokens, this provides different points of configuration that can allow you to quickly make changes at the broadest level (all projects), the narrowest level (individual email), and in between (individual project).

To see a list of all available email tokens and what they display, you can click the "?" (question mark) associated with the Content Token Reference at the top bottom of the email-ext section on the project configuration screen.

Token Macro Tokens

As of version 2.22, email-ext supports tokens provided by the token-macro plugin. You can see the available token-macro token below the email-ext tokens when you click the "?" (question mark) associated with the Content Token Reference at the bottom of the email-ext section on the project configuration screen.

Jelly content

New to version 2.9 is the ability to use Jelly scripts. Jelly scripts are powerful in that you can hook into the Jenkins API itself to get any information you want or need. There are two Jelly scripts packaged with the plugin and it is possible to write your own too.

There are two default Jelly scripts available out of the box; one is designed for HTML emails and the other is design for text emails. See the screenshots to the right for what these templates look like. You can specify which script you want by using the template argument. The usage for each script is the following:

You can also write your own Jelly scripts. The Jelly scripts are particularly powerful since they provide a hook into the Jenkins API including hudson.model.AbstractBuild and hudson.model.AbstractProject. For example on how to do this, take a look at the existing html and text scripts.

Using custom Jelly scripts (those not packaged with email-ext) requires the cooperation of your Hudson administrator. The steps are relatively simple:

  1. Create the Jelly script. The name of the script should be <name>.jelly. It is important the name ends in .jelly.
  2. Have your Jenkins administrator place the script inside $JENKINS_HOMEemail-templates.
  3. Use the Jelly token with the template parameter equal to your script filename without the .jelly extension. For example, if the script filename is foobar.jelly, the email content would look like this ${JELLY_SCRIPT,template="foobar"}.

Jelly script tips:

Script content

New to version 2.15 is the ability to use Groovy scripts. Scripts are powerful in that you can hook into the Jenkins API itself to get any information you want or need. There are two scripts with corresponding templates packaged with the plugin and it is possible to write your own too.

There are two default scripts and templates available out of the box; one is designed for HTML emails and the other is design for text emails. You can specify which script you want by using the script _argument, you can also just leave the default script and specify a different template file using the _template argument. Further, you can also include an init script that does some initialization using the init argument. The usage for each script is the following:

You can also write your own scripts and templates. The scripts are particularly powerful since they provide a hook into the Jenkins API including hudson.model.AbstractBuild and hudson.model.AbstractProject. For example on how to do this, take a look at the existing html and text scripts.

Using custom scripts (those not packaged with email-ext) requires the cooperation of your Jenkins administrator. The steps are relatively simple:

  1. Create the script/template. The name of the script end in the standard extension for the language (.groovy). The template can be named anything
  2. Have your Jenkins administrator place the script inside JENKINS_HOME\email-templates.
  3. Use the script token with the template parameter equal to your template filename, or in addition the script parameter equal to the custom script name. For example, if the template filename is foobar.template, the email content would look like this ${SCRIPT, template="foobar.template"}.

Template Examples

These are some useful examples for doing various things with the email-ext groovy templates.

jenkins-matrix-email-html.template

jenkins-generic-matrix-email-html.template

Pipeline Examples

See email-ext for command signatures

Notify Culprits and Requester via default EMail plugin

step([$class: 'Mailer', notifyEveryUnstableBuild: true, recipients: emailextrecipients([[$class: 'CulpritsRecipientProvider'], [$class: 'RequesterRecipientProvider']])])

Send an email to abc plus any addresses returned by the providers

emailext body: 'A Test EMail', recipientProviders: [[$class: 'DevelopersRecipientProvider'], [$class: 'RequesterRecipientProvider']], subject: 'Test', to: 'abc'


Attachments

New to version 2.15 is the ability to add attachments using the Ant pattern matching syntax used in many places in Jenkins. You can set a maximum total attachment size in the global configuration page, or it will be unlimited. 

Jive Formatter

jive-formatter.groovy contains methods for easy and convenient formatting of emails being sent from Jenkins to Jive. It should be called from the Pre-send Script area.

Also, it doesn't seem like Jive supports text with multiple formats, so only call one formatting method per block of text.

Either formatLine or formatText can and should be called on every line of text that will be sent to the Jive system prior to calling formatting methods like color or size. Please test on your own instances of Jive and add functionality as you find it!

The following lines should be added to the Pre-send Script area prior to attempting to invoke any functions.

File sourceFile = new File("/your/preferred/path/jive-formatter.groovy");
Class groovyClass = new GroovyClassLoader(getClass().getClassLoader()).parseClass(sourceFile);
GroovyObject jiveFormatter = (GroovyObject) groovyClass.newInstance();

Plugins

Extend Email-ext

 Make sure you have installed Maven 3 (why?) and JDK 6.0 or later. Make also sure you have properly configured your ~/.m2/settings.xml as explained in the Plugin Tutorial. This is needed to build properly any Jenkins plugin.

Check out and build

How to check out the source and build:

Version History

2.66 (March 21, 2019)

2.65 (March 6, 2019)

2.63 (August 5, 2018)

2.62 (March 23, 2018)

2.61 (October 27, 2017)

2.60 (September 19, 2017)

2.59 (September 12, 2017)

2.58 (Jun 29, 2017)

2.57.2 (April 10, 2017)

Jenkins administrators may need to approve scripts used by this plugin. Administrators can either proactively review all job configurations for Groovy scripts or they can wait for the jobs to run and fail. Approval is performed via the Script Security Plugin.


2.57.1 (March 20, 2017)

If the security fix is undesirable in a particular instance, it can be disabled with either or both of the following two system properties:

  • -Dhudson.tasks.MailSender.SEND_TO_UNKNOWN_USERS=true: send mail to build culprits even if they do not seem to be associated with a valid Jenkins login.
  • -Dhudson.tasks.MailSender.SEND_TO_USERS_WITHOUT_READ=true: send mail to build culprits associated with a valid Jenkins login even if they would not otherwise have read access to the job.


2.57 (February 18, 2017)

2.56 (February 14, 2017)

2.55 (February 11, 2017)

2.54 (January 22, 2017)

2.53 (December 23, 2016)

2.52 (October 23, 2016)

2.51 (September 28, 2016)

2.50 (September 24, 2016)

2.48 & 2.49 Failed releases

2.47 (August 7, 2016)

2.46 (August 4, 2016)

2.45 (July 31, 2016)

2.44 (June 13, 2016)

2.43 (June 4, 2016)

2.42 (April 17, 2016)

2.41.3 (Feb 23, 2016)

2.41.2 (Feb 18, 2016)

2.41 (Feb 07, 2016)

2.40.5 (Jun 08, 2015)

2.40.4 (May 24, 2015)

2.40.3 (May 20, 2015)

2.40.2 (May 13, 2015)

2.40.1 (May 4, 2015)

2.40 (April 28, 2015)

2.39.2 (January 30, 2015)

2.39 (November 16, 2014)

2.38.2 (August 26, 2014)

2.38.1 (June 2, 2014)

2.38 (May 24, 2014)

2.37.2.2 (March 8, 2014)

2.37.2 (January 26, 2014)

2.37.1 (January 11, 2014)

2.37 (January 8, 2014)

2.36 (October 26, 2013)

2.35.1 (October 14, 2013)

2.35 (October 12, 2013)

2.34 (September 15, 2013)

2.33 (September 12, 2013)

2.32 (August 13, 2013)

2.31 (August 12, 2013)

2.30.2 (May 23, 2013)

2.29 (May 6, 2013)

2.28 (April 4, 2013)

2.27.1 (March 5, 2013)

2.27 (March 2, 2013)

2.25 (December 12, 2012)

2.24.1 (July 20, 2012)

2.22 (June 15, 2012)

2.21 (May 16, 2012)

2.20 (April 12, 2012)

2.19 ( Mar 24, 2012 )

2.18 ( Jan 31, 2012 )

2.16 (Nov 07, 2011)

2.15 (Sep 05, 2011)

2.14.1 (Jul 01, 2011)

2.14 (Apr 21, 2011)

2.13 (Mar 23 2011)

2.12 (Feb 26, 2011)

2.11 (Feb 19, 2011)

This version requires Jenkins 1.396 or newer.

2.10 (Jan 20, 2011)

2.9 (Oct 14, 2010)

2.8 (Sept 15, 2010)

This version requires Hudson 1.356 or newer.

2.7 (Aug 30, 2010)

2.6 (Jul 20, 2010)

2.5 (Jan 20, 2010)

2.4 (Jan 7, 2010)

2.3 (Jan 6, 2010)

2.2.1 (Dec 23, 2008)