{"id":15045802,"url":"https://github.com/jenkinsci/poll-mailbox-trigger-plugin","last_synced_at":"2025-09-30T22:32:17.161Z","repository":{"id":15768218,"uuid":"18507124","full_name":"jenkinsci/poll-mailbox-trigger-plugin","owner":"jenkinsci","description":"A Jenkins plugin, to poll an email inbox, and trigger jobs based on new emails.","archived":false,"fork":true,"pushed_at":"2019-08-20T13:46:39.000Z","size":1125,"stargazers_count":40,"open_issues_count":31,"forks_count":32,"subscribers_count":111,"default_branch":"master","last_synced_at":"2024-09-30T09:16:43.640Z","etag":null,"topics":["adopt-this-plugin","email"],"latest_commit_sha":null,"homepage":"https://plugins.jenkins.io/poll-mailbox-trigger-plugin/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"nickgrealy/poll-mailbox-trigger","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenkinsci.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-04-07T05:20:57.000Z","updated_at":"2024-09-15T00:37:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jenkinsci/poll-mailbox-trigger-plugin","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fpoll-mailbox-trigger-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fpoll-mailbox-trigger-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fpoll-mailbox-trigger-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fpoll-mailbox-trigger-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkinsci","download_url":"https://codeload.github.com/jenkinsci/poll-mailbox-trigger-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234790034,"owners_count":18887084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adopt-this-plugin","email"],"created_at":"2024-09-24T20:52:17.695Z","updated_at":"2025-09-30T22:32:16.785Z","avatar_url":"https://github.com/jenkinsci.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GitHub release](https://img.shields.io/github/release/jenkinsci/poll-mailbox-trigger-plugin.svg)](https://github.com/jenkinsci/poll-mailbox-trigger-plugin/releases/latest)\n[![license](https://img.shields.io/github/license/jenkinsci/poll-mailbox-trigger-plugin.svg)](https://github.com/jenkinsci/poll-mailbox-trigger-plugin/blob/master/LICENSE)\n\n[![Build Status](https://api.travis-ci.org/jenkinsci/poll-mailbox-trigger-plugin.svg?branch=master \"Build Status\")](https://travis-ci.org/jenkinsci/poll-mailbox-trigger-plugin) [![Dependency Status](https://www.versioneye.com/user/projects/56d76c71d71695003886c352/badge.svg?style=plastic)](https://www.versioneye.com/user/projects/56d76c71d71695003886c352) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/a585091b3479458fafe53ec58e6a15e1)](https://www.codacy.com/app/nickgrealy/poll-mailbox-trigger-plugin?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=jenkinsci/poll-mailbox-trigger-plugin\u0026amp;utm_campaign=Badge_Grade) [![codecov](https://codecov.io/gh/jenkinsci/poll-mailbox-trigger-plugin/branch/master/graph/badge.svg)](https://codecov.io/gh/jenkinsci/poll-mailbox-trigger-plugin) [![Join the chat at https://gitter.im/jenkinsci/poll-mailbox-trigger-plugin](https://badges.gitter.im/jenkinsci/poll-mailbox-trigger-plugin.svg)](https://gitter.im/jenkinsci/poll-mailbox-trigger-plugin?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n# Poll Mailbox Trigger Plugin\n\nA Jenkins plugin, to poll an email inbox, and trigger jobs based on new emails.\n\nTable of contents\n---\n\n1. [Overview](#overview)\n    1. [Usage](#usage)\n    1. [Support](#support)\n    1. [Rationale](#rationale)\n1. [Building](#building)\n1. [Screenshots](#screenshots)\n1. [Configuration](#configuration)\n    1. [GMAIL (IMAPS)](#gmail-imaps)\n    1. [GMAIL (POP3S)](#gmail-pop3s)\n    1. [HOTMAIL](#hotmail)\n    1. [ZIMBRA](#zimbra)\n    1. [Office 365](#office-365)\n    1. [MS Exchange Server 2013](#ms-exchange-server-2013)\n    1. [Want to add a server example](#want-to-add-a-server-example)\n1. [Email Conventions](#email-conventions)\n1. [Troubleshooting](#troubleshooting)\n1. [Want to say thanks?](#want-to-say-thanks)\n\n__Additional:__\n\n1. [Releases / Changelog](https://github.com/jenkinsci/poll-mailbox-trigger-plugin/milestones)\n1. [Issues](https://github.com/jenkinsci/poll-mailbox-trigger-plugin/issues)\n1. [Wiki](https://wiki.jenkins-ci.org/display/JENKINS/Poll+Mailbox+Trigger+Plugin)\n1. [Source Code (GIT)](https://github.com/jenkinsci/poll-mailbox-trigger-plugin.git)\n1. [Authors](#authors)\n1. [License](#license)\n\nOverview\n---\n\nThe _poll-mailbox-trigger_ is a Jenkins \"build trigger\" plugin, which allows a Job to poll an email inbox.\nWhen an unread email is found, that matches the configured criteria, it:\n\n1. marks the email as read, so that it is not reprocessed\n1. triggers a new job\n\n\n### Usage\n\nOnce the plugin is installed, you can find it's configuration under **YourJob \u003e Configure \u003e Build Triggers \u003e Poll Mailbox Trigger**.\n[You should see something like this screenshot](#screenshots).\n\nFrom here you can configure:\n\n1. The email server and account to search for UNREAD emails - [here are some sample configurations for popular email services](#sample-configurations)\n1. Additional filters, including:\n   1. **folder** - the email folder to check (default \"INBOX\")\n   1. **subjectContains** - the email must inlcud this subject (default \"jenkins \u003e\")\n   1. **receivedXMinutesAgo** - the email must have been received within the last X minutes (default \"1440\" which is 24 hours)\n   1. [More configuration information is available here](#configuration)\n1. The polling schedule - defaults to every 5 minutes\n\nOnce configured, there is an option to **Test Connection**. This will tell you:\n1. If there are any errors - [please refer to the Troubleshooting section](#troubleshooting)\n1. If the plugin can connect to the mail server successfully\n1. How many emails it can find, that match the given criteria\n\nHit save, and you should be done.\n1. There will now be a \"View Polling Log\" option under your Job, so that you can see when the polling was last checked.\n1. The plugin will now start a new job instance, for each unread email it finds. Once an email has triggered a job, the\nemail will then be marked as READ, so that it doesn't invoke additional job instances in subsequent polling rounds.\n\n### Support\n\n| Compatibility | Since Version |\n| --- | --- |\n| Java Runtime Environment | 1.7+ |\n| Jenkins Server | 2.7.1 LTS |\n| Mail Server Protocols | IMAP, IMAPS, POP3, POP3S |\n\n### Rationale\n\nMainly, because I want to be able to (re)trigger a (failing) build, from the comfort of my home/beach/pub.\nI may not always have direct/sychronous access to the build server (due to firewalls, network access, etc).\nI'm already being notified by email when a job fails, why can't I just send an email response saying \"retry\"?\n\nIf you're working in a corporate environment, and are lucky enough to have a build server\n there's probably a __very__ small chance that the build server is also exposed to the outside world\n (without using a VPN).\n\nEmail is:\n\n1. prevalent - accessible pretty much anywhere\n1. convenient - it is built into my mobile phone\n1. asychronous - I can fire it now and let it get picked up later\n1. adopted - it's already being used to notify me of failed builds\n\nAlso, some side notes:\n\n1. I haven't met a Jenkins interface for mobile devices that I like.\n1. Email To SMS Gateways exist, for those that don't have Email on their mobile phones.\n1. Polling is not ideal\n\nAlternatives to polling?\n\n1. Utilising [Push-IMAP](http://en.wikipedia.org/wiki/Push-IMAP)\n1. Installing a sendmail/postfix server, forward emails to it, and write a perl script to process incoming emails.\n\nBuilding\n---\n\nPrerequisites:\n\n- JDK 6 (or above)\n\nTo setup for use with Intellij IDEA\n\n```Shell\n./gradlew cleanIdea idea\n```\n\nTo run Jenkins ([http://localhost:8080](http://localhost:8080)) locally with the plugin installed:\n\n```Shell\n./gradlew clean server\n```\n\nTo build the Jenkins plugin (.jpi) file:\n\n```Shell\n./gradlew clean jpi\n```\n\nTo publish/release the Jenkins plugin:\n\n1. Update the `version` in `gradle.properties`, to remove \"-SNAPSHOT\" (increment and re-add after publishing)\n2. Setup the `~/.jenkins-ci.org` credentials file as per the instructions here [https://wiki.jenkins-ci.org/display/JENKINS/Gradle+JPI+Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Gradle+JPI+Plugin)\n3. Ensure gradle is using `JDK7` (for dist compatibility) - `./gradlew --version`\n4. Then run the command:\n\n```Shell\n./gradlew clean publish\n```\n\n5. (todo) automate github version increment (and above steps?)\n\nScreenshots\n---\n\n_Screenshot - Version 1.022_\n\n![Version 1.022](src/main/site/images/screenshot-version-1.022.png \"Version 1.022\")\n\n\nConfiguration\n---\n\nThe \u003ci\u003eHost\u003c/i\u003e field, allows you to enter the DNS name/hostname/IP Address of the server, hosting the email account service.\n\nThe \u003ci\u003eUsername\u003c/i\u003e field, allows you to enter the username required to connect to this email account.\n\nThe \u003ci\u003ePassword\u003c/i\u003e field, allows you to enter the password (\u003cb\u003eN.B.\u003c/b\u003e or application password) required to connect to this email account.\n\nThe _Advanced Email Properties_ field, allows you to configure the plugin, using standard key=value property notation.\n\nYou can override the following default property values:\n\n    # Connection configuration\n    storeName=imaps\n\n    # Search configuration\n    folder=INBOX\n    subjectContains=jenkins \u003e\n    receivedXMinutesAgo=1440\n\n    # JavaMail configuration\n    mail.debug=true\n    mail.debug.auth=true\n    mail.imaps.host=\u003cabove_host\u003e\n    mail.imaps.port=993\n\nYou can also add [java imap properties](https://javamail.java.net/nonav/docs/api/com/sun/mail/imap/package-summary.html),\nto further configure the connection.\n\n### Sample Configurations\n\nBelow are some sample configurations for common web based email services:\n\n#### GMAIL (IMAPS)\nFor google passwords, go to \"Google account \u003e security \u003e app passwords\".\n\n    host=imap.gmail.com\n    username=\u003cyour_email\u003e@gmail.com\n    password=\u003cyour_application_password\u003e\n\n#### GMAIL (POP3S)\nFor google passwords, go to \"Google account \u003e security \u003e app passwords\".\n\n    host=pop.gmail.com\n    username=\u003cyour_email\u003e@gmail.com\n    password=\u003cyour_application_password\u003e\n    \n    storeName=pop3s\n\n#### HOTMAIL\nFor hotmail passwords, go to \"Account Settings \u003e Security Info \u003e Create a new app password\".\n\n    host=imap-mail.outlook.com\n    username=\u003cyour_email\u003e@hotmail.com\n    password=\u003cyour_application_password\u003e\n\n#### ZIMBRA\n    host=\u003cyour_mail_server\u003e\n    username=\u003cyour_email\u003e\n    password=\u003cyour_password\u003e\n\n#### [Office 365](#office-365 \"Thanks to Jason Swager for this contribution!\")\n    host=\u003cyour_mail_server\u003e\n    username=\u003cyour_email\u003e\n    password=\u003cyour_password\u003e\n    mail.imap.ssl.enable=true\n    mail.imap.starttls.enable=true\n\n#### [MS Exchange Server 2013](#ms-exchange-server-2013 \"Thanks to Shaun Alexander for this contribution!\")\n    host=\u003cyour_imap_host_server\u003e\n    username=\u003cyour_email\u003e\n    password=\u003cyour_password\u003e\n    mail.imaps.port=993\n    mail.imap.ssl.enable=true\n    mail.imap.starttls.enable=true\n\n#### Want to add a server example?\n    If you've managed to successfully setup a connection, \n    please contact me, and I'll update this section.\n\nEmail Conventions\n---\n\n### Job Parameters\n\nThe following build parameters, are injected into the job (sample values provided):\n\n#### From the Incoming Email\n\n|Name             |Sample value                                                |\n|-----------------|------------------------------------------------------------|\n|pmt_content      |\u0026lt;the email's content\u0026gt;                                 |\n|pmt_contentType  |multipart/ALTERNATIVE; boundary=1234                        |\n|pmt_flags        |SEEN                                                        |\n|pmt_folder       |INBOX                                                       |\n|pmt_from         |Me \u0026lt;Sender@gmail.com\u0026gt;                                 |\n|pmt_headers      |Delivered-To=Foobar@gmail.com etc                           |\n|pmt_messageNumber|14                                                          |\n|pmt_receivedDate |2014-10-14T12:19Z                                           |\n|pmt_recipients   |Foobar@gmail.com                                            |\n|pmt_replyTo      |Me \u0026lt;Sender@gmail.com\u0026gt;                                 |\n|pmt_sentDate     |2014-10-14T12:19Z                                           |\n|pmt_subject      |Jenkins \u0026gt; My Job                                         |\n\n#### From the poll-mailbox-trigger configuration\n\n|Name                   |Sample value    |\n|-----------------------|----------------|\n|pmt_mail.debug         |TRUE            |\n|pmt_mail.debug.auth    |TRUE            |\n|pmt_mail.imaps.host    |imap.gmail.com  |\n|pmt_mail.imaps.port    |993             |\n|pmt_host               |imap.gmail.com  |\n|pmt_username           |Foobar@gmail.com|\n|pmt_storeName          |imaps           |\n|pmt_receivedXMinutesAgo|1440            |\n|pmt_subjectContains    |Jenkins \u0026gt;    |\n\n#### Calculated values (pmt_subject - pmt_subjectContains)\n\n|Name                   |Sample value    |\n|-----------------------|----------------|\n|pmt_jobTrigger         |My Job          |\n\nN.B. Please note, these variables are injected into the triggered build (only). No other actions (implied or assumed)\nare taken. (e.g. No jenkins node filtering is performed, unless you've configured the job to do so. No additional jobs\nare triggered, unless you've configured the job to do so. And so on.)\n\n#### Helpful Tips\n\n##### Simple \"Retry\" email link on failed builds\n\n1. Setup a \"Mail Trigger\" job, which builds other jobs based on the \"pmt_jobTrigger\" value.\n1. Setup an editable Email notification on the target job, so that it emails you when a job has failed.\n1. Include the following html, in the editable Email job configuration.\n\n    `\u003ca href=\"mailto:\u003cjenkins_poll_mailbox\u003e@gmail.com?subject=Jenkins \u003e $JOB_NAME\"\u003eRetry $JOB_NAME\u003c/a\u003e`\n\nThat way, when the job fails, it will email you a nice \"Retry My Job\" link. Clicking on it, opens a new email, which\nyou can just send straight away (good for mobile phones).\n\n### Custom Job Parameters\n\nAs of version 0.15, you can pass addition custom job parameters to the new build, by simply putting key=value property\nnotation into the content of your email. N.B. both `text/plain` and `text/html` content types are supported. Emails\nwith attachments have not yet been tested.\n\nFor example:\n\n    Hi Jenkins,\n\n    Please execute the job with these parameters:\n\n    fruit=banana\n    veg=carrot\n    email=foobar@abc.com\n\n    --\n    Kind regards,\n\n    Nick\n\nWill inject the following job parameters into the new job instance:\n\n|Name    | Value           |\n|--------|-----------------|\n|fruit   | banana          |\n|veg     | carrot          |\n|email   | foobar@abc.com  |\n\nTroubleshooting\n---\n\n###1a. Error : javax.mail.MessagingException: Connection timed out: connect;\n###1b. Error : javax.mail.MessagingException: Connection refused;\n\n__Solution:__ Check the Jenkins server can access the email server and port, by running the command (from the Jenkins server):\n\n    telnet \u003cyour_host\u003e \u003cyour_port_143_or_993\u003e\n\nIf you get a message similar to the following, then there is no way to create a direct connection to the mail server - probably\nthe network is down, or the connection has been (a: passively / b: actively) blocked by a firewall. If so, please check your network settings with\nyour network administrator. You may need to specify SOCKS proxy details, in the \u003ci\u003eAdvanced Email Properties\u003c/i\u003e.\n\n    Connecting To imap.gmail.com...Could not open connection to the host, on port 993: Connect failed\n\n###2. Error : javax.mail.AuthenticationFailedException: [AUTHENTICATIONFAILED] Invalid credentials (Failure)\n\n__Solution:__ Check the credentials you're using are correct.\n\n###3. Error: javax.mail.MessagingException: com.ibm.jsse2.util.j: PKIX path building failed: java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid CertPath.; ...\n\n__Solution:__ To ignore certificate verification errors, you can use the following config property:\n\n    mail.imaps.ssl.trust=*\n\n__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:\n\n    javax.net.ssl.trustStrore=/path/to/cacerts.jks\n\n###4. Error : java.lang.NullPointerException at org.jenkinsci.plugins.pollmailboxtrigger.PollMailboxTrigger.initialiseDefaults(PollMailboxTrigger.java:98)\n\n__Solution:__ I'm not quite sure what the cause is! If you're able to reproduce the issue, please contact me with instructions.\nIn the meantime, the error is caught and the following message is displayed.\n\n    Could not get Jenkins instance using Jenkins.getInstance() (returns null). This can happen if Jenkins\n    has not been started, or was already shut down. Please see\n    http://javadoc.jenkins-ci.org/jenkins/model/Jenkins.html#getInstance() for more details. If you believe\n    this is an error, please raise an 'issue' under\n    https://wiki.jenkins-ci.org/display/JENKINS/poll-mailbox-trigger-plugin.\n\n###5. Error : java.net.UnknownHostException: imaps.gmail.com\n\n__Solution:__ The hostname provided doesn't exist in the DNS servers. Please check that it is correct.\n\n###6. Error : Please set the 'folder=XXX' parameter to one of the following values:\n\n__Solution:__ The provided folder name doesn't exist on the folder, please use one of the values listed.\n\n\nWant to say thanks?\n---\n\nWant to say thanks but can't find the words? [Coffee donations are VERY welcome](http://nickgrealy.github.io/)!\n\n![http://wrldhq.com/2014/02/12/new-meaning-to-the-term-coffee-drip-coined/](src/main/site/images/star-wars-coffee.jpg \"http://wrldhq.com/2014/02/12/new-meaning-to-the-term-coffee-drip-coined/\")\n\n\n---\n\nAuthors\n---\n\nNick Grealy - \u003cnickgrealy@gmail.com\u003e\n\nLicense\n---\n\nLicensed under the [MIT License (MIT)](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fpoll-mailbox-trigger-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkinsci%2Fpoll-mailbox-trigger-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fpoll-mailbox-trigger-plugin/lists"}