Incoming Mail Connections

To use mail handlers and process your incoming emails to create or modify issues, incoming Mail Accounts have to be configured first.

Due to security reasons, the Email This Issue add-on cannot access the mail servers in Jira itself, so mail accounts should be configured within Email This Issue's Administration interface.

1. Go to the Administration configuration tab, and choose Incoming Mail Connections under the INCOMING MAILS menu item.

2. To create a new Incoming Mail Connection, click on Add.

3. Email This Issue supports login and OAuth authentication mechanisms for Incoming Mail Connections. In the Add Incoming Mail Connection dialog, select the correct protocol:

• POP3, IMAP: log in with username and password

• OAuth for Gmail/Gsuite: OAuth2

• OAuth2 for Microsoft 365

Incoming Mail Connections are always added in a disabled state. After editing an enabled Incoming Mail Connection its state will change back to disabled.

In case of an unsuccessful connection in the Incoming Mail Connection, the status becomes red and a protocol log becomes available:

The Protocol Log is displayed only when the status is red (indicating a problem with the connection) and it contains information about the errors that occurred during fetching e.g. authentication failed, wrong hostname etc.

Currently Email This Issue only deletes e-mails - after they are processed - if the email was unread, before the process, and the "Delete emails from account" option is selected under the "After download" option. Before saving the Incoming Mail Connection, please use the "Test Connection" button to check if Email This Issue is able to connect to your mailbox.

After creating Incoming Mail Connections, go to Mail Handlers to configure the actions that should be executed when processing new emails.

OAuth 2.0 Settings

OAuth authentication is currently supported for both Google and Microsoft 365 accounts.

If you want to use OAuth 2.0 authentication, select this option with the appropriate protocol. A new dropdown list and button will appear under the protocol selector.

Microsoft Oauth 2.0 host settings

When it comes to accessing your Microsoft Mail account with OAuth2, there is an option to choose between two distinct protocols: IMAP and Microsoft Graph.

For IMAP connections, the hostname "outlook.office365.com" is used by default, when connecting to the mail server. However, in certain scenarios, the use of a custom hostname might be required. In such cases, there is a possibility to override the default value by enabling the respective "Override default host setting" toggle and selecting the desired host from the "Host" dropdown appearing below.

OAuth 2.0 Settings for Google

1. Select the Client Credentials you created on the credentials page.

2. Enter the user name to the SMTP Server you want to use.

3. Click on the "Authorize with Google" button to grant access to Email This Issue to send emails from your account.

4. In the dialog, select the account which belongs to the email address you use for login: Note: If you have multiple Google accounts select the one with the email that matches the username in the SMTP Server dialog. Emails will be sent from that account.

5. If you get the following warning, do the following:

   1. Click Advanced.

   2. Click the "Go to meta-inf.hu (unsafe)" link.

   3. Confirm your choice by clicking Allow.

If you want to revoke the access from Email This Issue to your Gmail account, you can do it by visiting Account Settings.

Shared mailbox settings

A shared mailbox is a mailbox that multiple users can use to read and send e-mail messages. You can read more about them here: https://docs.microsoft.com/en-us/exchange/collaboration/shared-mailboxes/shared-mailboxes

To use a shared mailbox you just have to enter the username and password (or use OAuth) of the account you want to log in with, then enable the "Use a shared mailbox" option and enter the alias of the shared mailbox in the field that appears:

Email Security

If you would like to process encrypted emails with Email This Issue, a Certificate can be added to the Incoming Connection that will be used by the Mail Handler. One Connection can have multiple Certificates, and one Certificate can be added to multiple Connections. You can search for certificates by starting to type their name or alias into the select field search bar. They will appear with their name first and alias in parentheses.

Enabling Incoming Mail Connections

By default, all new Incoming Mail Connections are created as disabled. To enable a connection, select the "Enable" option from the connection's menu.

From the app's point of view, when initializing a new or re-activating (re-enabling) a previously used ("known") mailbox - provided that there is a matching enabled mail handler for the connection at hand - there is a good chance that a bunch of messages will be subsequently downloaded from the mailbox and processed by the app (by creating or updating issues).

Depending on the contents and the current state of the mailbox, such an action might entail some risks though:

• lots of emails might be processed inadvertently (which may take a while, while also changing messages' state on the mail server by marking them as SEEN or DELETED)

• under certain circumstances (depending on the mail server's and the app's settings), duplicate issues might be created

To avoid the undesired download of a large number of emails upon enabling a connection, the estimated number of 'new' messages within the target mail folder is assessed and an informational dialog is popped up if an acknowledgement is required before acting.

Searching for new messages (in progress):

If there are any new messages to download, the following text is displayed: Clicking on the Enable button will change the connection's state and trigger other processes as indicated by the appearing flag:

Filtering the list

The Incoming Mail Connection list can be filtered by clicking on the Search button. After clicking, a free text field will be opened, in which the search term can be entered. The filter searches in the Name, Description, Host, and Username fields.