Email This Issue
Email This Issue - for Jira Server/Data Center

Incoming Mail Connections


Comparison of Mailbox Management in Jira and Email This Issue

Email This Issue now manages connections to Mail Accounts to override limitations in Jira's IMAP/POP3 management.
Problems/Limitations in Jira's legacy Mailbox management
How Email This Issue tackles them
Emails removed from mailboxes
Email This Issue does not delete the emails from your mailboxes, it simply marks them "read".
Huge latency (even hours) in incoming mail processing when there are many emails in the mailbox.
Email This Issue's mailbox management is more intelligent than its predecessors' as it continues downloading emails at the point where the last iteration has left off.
No insight of emails being downloaded or processed.
Email This Issue includes Incoming Mail Queue and Incoming Mail Log components that allow admins to monitor what happens with the emails received from the mailbox
Emails are in-memory (once emails are downloaded, they are stored in memory and passed to a handler). If Jira crashes while processing a message, the message is lost.
Email This Issue downloads the emails from the mailboxes and stores them in the database persistently.
If the download is interrupted by a malfunction of Jira, Email This Issue attempts to download it again.

Incoming Mail Connections

To see the list of mailbox connections go to INCOMING EMAILS ADMINSTRATION --> Incoming Mail Connections.
Incoming Mail Connections page has a set of mandatory and options attributes. The new Protocol Attribute is used to specify if the connection to the provider is based on password authentication or on OAuth2.

Add a new Incoming Mail Connection with Password Authentication

To add a new Incoming Mail Connection, click the Add button.
If you’re working on a production account that already has emails in the inbox (read or unread), remove everything you don’t want to be processed. This is needed because at the first processing round we download every email from the target folder. Later on, we only download those that have not been processed yet.

Add a new Incoming Mail Connection with OAuth2 Authorization

When using the OAuth2 connection protocol, a reduced set of fields are shown because attributes like host, port, password are not required.

OAuth2 Authorization

If you want to connect to an email service using OAuth2, after specifying the OAuth Credential and Username, you must start the authorization process by clicking the Authorization button.
The authorization is specific to the service provider. The procedure is detailed here:

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:
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:
Shared mailbox settings for Incoming Mail Connection

Incoming Mail Connection attributes

Applicable to Protocols
Unique name of the IMAP or POP3 connection
A longer description of the purpose of this connection
Specifies the protocol to use when connecting the service. Values are:
  • IMAP
  • POP3
  • Google OAuth2
  • Microsoft OAuth2 (coming soon in version 8.1.1)
OAuth2 Credentials
This is a new attribute that is used when OAuth2 authorization is activated. It selects the OAuth2 Client Credential to be used when connecting this service.
Supported encryptions:
  • No encryption
The hostname or IP addresses of the IMAP or POP3 server
Optional, if not specified, we use the default ports. Leave blank or 0 for default (for POP3 plain: 110, SSL/TLS: 995; for IMAP plain:143, SSL/TLS: 993).
The period in minutes the Incoming Mail Connections are connected to mailboxes.
IMAP or POP3 connection timeout in milliseconds, valid value: 1-30000 ms. Leave blank or 0 for default (30000 ms).
The Folder in the mailbox from which the emails will be downloaded. If left blank, emails are loaded from the INBOX folder.
The Folder attribute is only used when the protocol is IMAP.
Connection credentials.
Shared mailbox alias
Connection credentials.
Connection credentials. Please note that the password should only contain ASCII-characters.

Decide what to do after Emails are downloaded

By default (and up to version 8.1.1) Incoming Mail Connections mark downloaded emails as "seen" (i.e. "read") in the mailboxes. Since version 8.1.1 administrators may configure Incoming Mail Connections to remove messages from the mailboxes after they have been successfully downloaded.
In case of POP3 connections settings on Email client's side might override Email This Issue settings.
Note: If you are using Microsoft Exchange, you can create a rule to directly copy each incoming mail into a separate folder (e.g. “Jira Archive”).
Instead of using the setting “Mark messages as seen”, set the After download function in the Incoming Mail Connection to the “Delete messages” option. This way the inbox is kept clean and empty, but you still have a copy of all your emails.
Processing time in large mailboxes is reduced to seconds instead of minutes with this little workaround.

Test Connections

It is possible to test the connection before actually saving the connection itself, it is also highly recommended to do so in order to check if there are any errors in the configuration.
After pressing the test connection button, the following pop-up comes up if the connection is successful:

How to use Incoming Mail Connections

These Incoming Mail Connections cannot be used with Jira's built-in Incoming Mail Handlers, only with our app's Next Generation Mail Handlers.
Important: We highly recommend keeping the inbox only be accessible by the app and not manually by users. If any users read the emails from the inbox before we get to process them (and they will be marked "read") we will not be able to process the emails. If this happens though, do the following:
1. Move the "read" emails out of the folder.
2. Make them "unread".
3. Move them back into the folder manually.

Enabling Incoming Mail Connections

All new Incoming Mail Connections are created as disabled by default. To enable a connection select the enable option from the connection's menu.
To avoid downloading many new emails from the target folder, we've built in an automatic check to look for new messages in the Incoming mail connection's target folder before enabling the connection.
IMAP or OAuth2 connections
POP3 connections
Searching for new messages in the Email Client:
If there are any new messages to download then the result will show as below:
Clicking on the enable button will start the enabling process, and finally the following flag will be shown:
In case of POP3 connections, we can not count an exact number of new messages, because this connection type is handled different way in each email clients. To be sure you don't download (and process by a mail handler) a bunch of emails, clean your inbox folder.
Clicking on the enabling will starts the enabling process, and finally the following flag shown: