Mail Handler


Starting with Power Scripts for Jira 4.0, we've added the ability to use SIL scripts to process incoming emails.

Specific SIL integrations

Power Scripts provides a set of specific routines for use withing mail handling scripts that enable you to read the contents of the incoming email and handle any attachments, as described below.

Predefined structure: IncomingEmail

Incoming Email


string []

Array of email addresses


string []

Array of email addresses


string []

Array of email addresses





Entire body of the message including quoted text in case of replied or forwarded messages


string []

Array containing the names of the attachments; there can be duplicates

Writing the handler script

There are the following important things to note about the mail handler script:

  1. If the first email address in the from field (the sender of the email) belongs to a registered Jira user, the script will be run as that user, that is currentUser() will return that user. Otherwise, the script will be run as an anonymous user.
  2. The return value of the script dictates if other mail handlers will be called for the email or not. 
    1. If the script returns true or has no return value, the email is considered as "handled" and subsequent mail handlers will not be called.
    2. If the script returns false or throws an error, the email is considered "not handled" and subsequent mail handlers will be called.

Here is an example of a mail handler equivalent to Jira's built in "Create issue or add comment".

IncomingEmail mail = getIncomingEmail();

string issueKey = matchText(mail.subject, "[A-Z][A-Z]+-[0-9]+"); // find an issue key in the subject
if(isNull(issueKey)) {
	// if no issue key found, create a new issue
    string [] fields = {};
    fields += {"reporter", currentUserKey()};
    fields += {"assignee", getUserByEmail([0]).key}; 

    string newIssue = createIssue("TEST", "", "Task", mail.subject, "Minor", mail.body, {}, "", "", 0, fields);
    %newIssue%.watchers = getUserKeysFromEmails(; 
} else {
	// if issue key found in subject, add a comment
    addComment(issueKey, currentUserKey(), mail.body);

You might find the getUserByEmail and getUserKeysFromEmails routines useful.

Adding the SIL Mail Handler

To add a new SIL Mail Handler:

  1. Go to Administration > System > Incoming Mail and click Add incoming mail handler.

  2. Fill in the necessary fields:
    • Mail Handler name
    • Incoming server to use
    • Delay between running time
    • Select the SIL Mail Handler
    Click Next.
  3. In the next screen, select the script to use for the handler and click Add.

To delete the mail handler, use the standard Jira feature.

That's it!

See also

Mail Handler Routines

  • Page:
    saveAttachmentFromEmail — Saves the attachment file from the incoming email to a specific file path.
  • Page:
    getIncomingEmail — Retrieves a structure containing information about the incoming email such as sender, recipients, subject, or body.
  • Page:
    attachAllFilesFromEmail — Attaches all attachments from the incoming email to a specific issue.
  • Page:
    attachFileFromEmail — Attaches a single file from the incoming email to a specified issue.