[](https://wiki.jenkins-ci.org/display/JENKINS/Poll Mailbox Trigger Plugin)

Poll Mailbox Trigger Plugin

A Jenkins plugin, to poll an email inbox, and trigger jobs based on new emails.

Table of contents

1. Overview
2. Building
3. Screenshots
4. Configuration
   1. GMAIL
   2. HOTMAIL
   3. ZIMBRA
   4. Office 365
   5. MS Exchange Server 2013
   6. Want to add a server example
5. Email Conventions
6. Troubleshooting
7. Want to say thanks?

Additional:

1. Changelog
2. Backlog
3. Wiki
4. Source Code
5. Issue Tracking
6. Authors
7. License

Overview

The poll-mailbox-trigger allows a build to poll an email inbox using the imap protocol. When an unread email is found matching the configured criteria, it:

1. marks the email as read, so that it is not reprocessed
2. triggers a new job

Why?

Mainly, because I want to be able to (re)trigger a (failing?) build, from the comfort of my home/beach/pub. I may not always have direct/sychronous access to the build server (due to firewalls, network access, etc). I'm already being notified by email when a job fails, why can't I just send an email response saying "retry"?

If you're working in a corporate environment, and are lucky enough to have a build server there's probably a very small chance that the build server is also exposed to the outside world (without using a VPN).

Email is:

1. prevalent - accessible pretty much anywhere
2. convenient - it is built into my mobile phone
3. asychronous - I can fire it now and let it get picked up later
4. adopted - it's already being used to notify me of failed builds

Also, some side notes:

1. I haven't met a Jenkins interface for mobile devices that I like.
2. Email To SMS Gateways exist, for those that don't have Email on their mobile phones.
3. Polling is not ideal

Alternatives to polling?

1. Utilising Push-IMAP
2. Installing a sendmail/postfix server, forward emails to it, and write a perl script to process incoming emails.

Building

Prerequisites:

• JDK 6 (or above)

To setup for use with Intellij IDEA

./gradlew cleanIdea idea

To run Jenkins (http://localhost:8080) locally with the plugin installed:

./gradlew clean server

To build the Jenkins plugin (.jpi) file:

./gradlew clean jpi

To publish/release the Jenkins plugin:

1. Update the version in gradle.properties, to remove "-SNAPSHOT" (increment and re-add after publishing)
2. Setup the ~/.jenkins-ci.org credentials file as per the instructions here https://wiki.jenkins-ci.org/display/JENKINS/Gradle+JPI+Plugin
3. Then run the command:

./gradlew clean publish

Screenshots

Screenshot - Version 1.022

Configuration

The Host field, allows you to enter the DNS name/hostname/IP Address of the server, hosting the email account service.

The Username field, allows you to enter the username required to connect to this email account.

The Password field, allows you to enter the password (N.B. or application password) required to connect to this email account.

The Advanced Email Properties field, allows you to configure the plugin, using standard key=value property notation.

You can override the following default property values:

# Connection configuration
storeName=imaps

# Search configuration
folder=INBOX
subjectContains=jenkins >
receivedXMinutesAgo=1440

# JavaMail configuration
mail.debug=true
mail.debug.auth=true
mail.imaps.host=<above_host>
mail.imaps.port=993

You can also add java imap properties, to further configure the connection.

Sample Configurations

Below are some sample configurations for common web based email services:

GMAIL

For google passwords, go to "Google account > security > app passwords".

host=imap.gmail.com
username=<your_email>@gmail.com
password=<your_application_password>

HOTMAIL

For hotmail passwords, go to "Account Settings > Security Info > Create a new app password".

host=imap-mail.outlook.com
username=<your_email>@hotmail.com
password=<your_application_password>

ZIMBRA

host=<your_mail_server>
username=<your_email>
password=<your_password>

Office 365

host=<your_mail_server>
username=<your_email>
password=<your_password>
mail.imap.ssl.enable=true
mail.imap.starttls.enable=true

MS Exchange Server 2013

host=<your_imap_host_server>
username=<your_email>
password=<your_password>
mail.imaps.port=993
mail.imap.ssl.enable=true
mail.imap.starttls.enable=true

Want to add a server example?

If you've managed to successfully setup a connection, 
please contact me, and I'll update this section.

Email Conventions

Job Parameters

The following build parameters, are injected into the job (sample values provided):

From the Incoming Email

Name	Sample value
pmt_content	<the email's content>
pmt_contentType	multipart/ALTERNATIVE; boundary=1234
pmt_flags	SEEN
pmt_folder	INBOX
pmt_from	Me <[email protected]>
pmt_headers	Delivered-To=[email protected] etc
pmt_messageNumber	14
pmt_receivedDate	2014-10-14T12:19Z
pmt_recipients	[email protected]
pmt_replyTo	Me <[email protected]>
pmt_sentDate	2014-10-14T12:19Z
pmt_subject	Jenkins > My Job

From the poll-mailbox-trigger configuration

Name	Sample value
pmt_mail.debug	TRUE
pmt_mail.debug.auth	TRUE
pmt_mail.imaps.host	imap.gmail.com
pmt_mail.imaps.port	993
pmt_host	imap.gmail.com
pmt_username	[email protected]
pmt_storeName	imaps
pmt_receivedXMinutesAgo	1440
pmt_subjectContains	Jenkins >

Calculated values (pmt_subject - pmt_subjectContains)

Name	Sample value
pmt_jobTrigger	My Job

N.B. Please note, these variables are injected into the triggered build (only). No other actions (implied or assumed) are taken. (e.g. No jenkins node filtering is performed, unless you've configured the job to do so. No additional jobs are triggered, unless you've configured the job to do so. And so on.)

Helpful Tips

Simple "Retry" email link on failed builds

1. Setup a "Mail Trigger" job, which builds other jobs based on the "pmt_jobTrigger" value.

2. Setup an editable Email notification on the target job, so that it emails you when a job has failed.

3. Include the following html, in the editable Email job configuration.

   <a href="mailto:<jenkins_poll_mailbox>@gmail.com?subject=Jenkins > $JOB_NAME">Retry $JOB_NAME</a>

That way, when the job fails, it will email you a nice "Retry My Job" link. Clicking on it, opens a new email, which you can just send straight away (good for mobile phones).

Custom Job Parameters

As of version 0.15, you can pass addition custom job parameters to the new build, by simply putting key=value property notation into the content of your email. N.B. both text/plain and text/html content types are supported. Emails with attachments have not yet been tested.

For example:

Hi Jenkins,

Please execute the job with these parameters:

fruit=banana
veg=carrot
[email protected]

--
Kind regards,

Nick

Will inject the following job parameters into the new job instance:

Name	Value
fruit	banana
veg	carrot
email	[email protected]

Troubleshooting

###1. Error: javax.mail.AuthenticationFailedException: AUTHENTICATE failed. Solution: Check the credentials you're using are correct.

###2. Error: javax.mail.MessagingException: com.ibm.jsse2.util.j: PKIX path building failed: java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid CertPath.; ... Solution: To ignore certificate verification errors, you can use the following config property:

mail.imaps.ssl.trust=*

Warning: it's not advisable to ignore certificate verification errors (unless perhaps in a test environment): this defeats the point of using SSL/TLS. Instead, if you know you trust that server certificate, import it in your trust store, and specify the location of the trust store using:

javax.net.ssl.trustStrore=/path/to/cacerts.jks

###3. Error : javax.mail.MessagingException: Connection timed out: connect; Solution: Check the Jenkins server can access the email server and port, by running the command (from the Jenkins server):

telnet <your_host> <your_port_143_or_993>

If you get a message similar to the following, then there is no way to create a direct connection to the mail server - probably the network is down, or the connection has been blocked by a firewall. If so, please check your network settings with your network administrator. You may need to specify SOCKS proxy details, in the Advanced Email Properties.

Connecting To imap.gmail.com...Could not open connection to the host, on port 993: Connect failed

###4. Error : java.lang.NullPointerException at org.jenkinsci.plugins.pollmailboxtrigger.PollMailboxTrigger.initialiseDefaults(PollMailboxTrigger.java:98) Solution: I'm not quite sure what the cause is! If you're able to reproduce the issue, please contact me with instructions. In the meantime, the error is caught and the following message is displayed.

Could not get Jenkins instance using Jenkins.getInstance() (returns null). This can happen if Jenkins
has not been started, or was already shut down. Please see
http://javadoc.jenkins-ci.org/jenkins/model/Jenkins.html#getInstance() for more details. If you believe
this is an error, please raise an 'issue' under
https://wiki.jenkins-ci.org/display/JENKINS/poll-mailbox-trigger-plugin.

Want to say thanks?

Want to say thanks but can't find the words? Coffee donations are VERY welcome!

ChangeLog

1.020

1. If the "script" property has spaces only (someone might have pressed some spaces by mistake), the CustomProperties class still should recognized it as empty (.equals(""))
2. The default values of the properties were being loaded AFTER loading the user-provided ones. For instance I want to get rid of the subject filter "jenkins >" and I cannot do that, because when I add the property with the empty value, this default takes over. Thus, I submit this PR to change the order in which these data is loaded: first we load the defaults, THEN we load the user-provided values

1.018

1. Fixed defect in Session.getDefaultInstance -> getInstance
2. Changed build process to use gradle

0.15

1. Fixed defect in parsing properties

0.14

1. Added ability to inject 'custom variables' as job parameters
2. Added handling for multipart emails
3. Improved handling of node properties (thanks Charlie Stott!)

0.12

1. Changed deprecated code - Hudson.getInstance() to Jenkins.getInstance()
2. Added exception handling, to provide a more informative error when Jenkins.getInstance() returns null.

0.11

1. interpret email body directly as build parameters (see mailto links)
2. Test using variable replacement!
3. Add config as build parameters

0.9

1. Change package dependencies, so that there is no dependency on ScriptTrigger (for future cloudbees support)
2. Implemented encrypted passwords (test connections using SSH keys)

0.8

1. Added default properties (to minimise configuration)
2. Documented and tested (successfully) configurations for the common web based email services.

0.5

1. Added a "Test Connection" button

0.4

1. get this plugin published under jenkinsci!

0.2

1. Add email properties (e.g. to, from, cc, bcc, subject, body) as job parameters (pmt_*)

---

Authors

Nick Grealy - [email protected]

License

Licensed under the MIT License (MIT)