Mail Handlers process downloaded (fetched) emails from the inboxes configured in Mail Accounts. Every Mail Handler is linked to a Mail Account and defines the actions that should be executed when an incoming email is processed.
It is important to know a little background information how these Mail Handlers work:
- First, Accept email is checked. This can be used to filter messages in a mailbox if it has multiple email addresses (like mail aliases). By default, all messages are passed through, regardless of the recipient addresses.
- If Accept email is set to if any recipient equals to any of the following addresses then email is processed if To/CC/BCC address equals to any of the specified email addresses
- If Accept email is set to if any recipient matches any of the following regular expressions then email is processed if To/CC/BCC address matches to any of the specified regular expressions
- Secondly, they to find the user on behalf the actions will be executed, using the From address in the email.
- If the user is found, then it will be used as Reporter for creating issues, the Author for adding comments, the user who executes transitions, etc...
- If the user is not found and Default reporter is set in the Mail Handler, then the Default Reporter will be used
- If the user is not found and Default reporter is not set, then execution is aborted
- Thirdly, the mail handler tries to find to corresponding issue
- First it looks for an issue key in the subject
- It extracts parts from the mail Subject that look like an issue key.
- It checks if there is an issue with the extracted issue key
- If issue does not exist, then it continues with next extracted part from the Subject that look like an issue key
- it looks for an issue Id in the Message-Id In-reply-to header
- it looks for an issue Id in the Message-Ids in the References header
- Finally, actions are processed
- If an issue was found, it will be remembered and actions like Add comment, Execute transition, Send auto reply, etc... can use this issue
- If issue was not found, then the first action that is executed should be a Create Issue action.
Mail Handler configuration dialog has two tabs. On the first tab, general parameters can be configured.
- Set the linked account from the available Mail Accounts
- Set the Default reporter to any valid user as a fallback, when the user can not be determined by the From address. By default, there is no fallback user and processing will be aborted if no user can be found by the From address
- If fallback to default reporter is set, then Email This Issue retries executing the action with the selected default reporter if the execution with the current reporter fails due to permission error.
- Set Catch email to configure the email addresses or regular expressions that should match with the To/CC/BCC address. By default, it is disabled
- If it is set to Equals to any of the following addresses, then emails will be processed only if the To/CC/BCC address of the email equals to any of the specified email addresses.
For example, if you have a mailbox email@example.com with aliases firstname.lastname@example.org and email@example.com and you want to process only emails sent to example.net or example.org (not example.com), then add two lines in the appearing text area:
- If it is set to Matches any of the following regexps, then emails will be processed only if the To/CC/BCC address of the email matches with any of the specified regular expressions.
For example, if you have a mailbox with addresses firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com and want to process email that are sent to addresses starting with support, then add this line in the appearing text area (note that dot is escaped before .com):
- Filters are used during mail fetch. If a mail is filtered by these filters, it will not be enqueued for processing.
- Filter auto reply emails: Filters auto reply emails. All emails which have the header "Auto-Submitted" with a value other than no, will be considered as auto reply and will be filtered out if this filter is enabled
- Filter bulk emails: Filters bulk emails. It checks whether the Precedence header with the value "bulk" is set in the email.
- Filter delivery status notifications: Filters delivery status notification emails. This wilter checks if the content type is multipart/report and contains "report-type=delivery:status"
- Filter mails sent from JIRA: Filters emails sent from a Jira or JETIC instance. It checks the presence of X-JIRA-Fingerprint and X-JETI-Fingerprint headers and filters the email if any of them is present.
- Although not a setting in the mail accounts, but it is important to note that only those emails are processed by the mail handler that are "unread" in the time of receiving the original email.
After general settings are configured, switch to the second tab (Rules and actions) to set up the mail handler actions that should executed during processing the incoming mail