Email This Issue
📈 Marketplace❓ Support❤️ Feedback🏠 META-INF Apps
Email This Issue - for Jira Server/Data Center
Email This Issue - for Jira Server/Data Center
  • ⬇️Start Here
  • Email This Issue - for Jira Server/DC
  • Features
  • Secure the email channel with Email This Issue
  • Comparing Email This Issue and Jira Server/DC
  • 🤓Documentation
    • Outgoing Emails
      • Sending manual emails
        • The difference between email editors
        • Enabling template categories so templates can be chosen on the Email screen
        • Mail Generation Queue (formerly called Event Queue)
        • Manual Email Default Settings
      • Sending issue filters by email
      • Email templates
        • Adding custom macro to email templates
        • Adding Email Audit Log to email templates
        • Adding fields to email templates
        • Adding issue comments to emails
        • Adding issue link information to your template
        • Adding issue operation links to the email
        • Adding a signature with a company logo to emails
        • Adding user properties to emails
        • Disabling links and avatars or icons in templates
        • Formatting Date and Time values
        • Using reply templates
        • Using Mail Body Initializer templates
        • Rendering templates within templates
        • Velocity Context in email templates
        • Formatting number values
        • Searching for issues in email templates
        • Changelog information in email templates
        • Canned responses
      • Contexts
        • Context Resolution Algorithm
      • Event Notifications
      • Distribution lists
      • Workflow post functions
      • Custom fields
    • Incoming Emails
      • Attachment Filtering
      • Next Generation Mail Handlers
        • Jira automation and Next Generation Mail Handlers
        • Using regular expressions
      • Classic Mail Handlers - Deprecated
        • Mail Handler Error Log
        • Step-by-step Classic Mail Handler to Next Generation Mail Handler migration aid
        • Field Rules
        • Phasing out the Classic Mail Handler
        • Comparing the Classic and the Next Generation Mail Handlers
    • Integrations
      • CRM for Jira
      • nFeed
      • Glass Documentation
      • API - Integration with other services
    • Administration
      • General configuration
      • Email Audit Log
      • Outgoing Mail Connections
      • Outgoing Mail Queue
      • Incoming Mail Connections
      • Incoming Mail Queue
      • Incoming Mail Log
      • Backup and restore settings
        • Backup and restore administration
          • Backup menu
          • Restore menu
        • Backup and Restore Tutorials
          • Backup and restore for empty email settings
          • Backup and restore only parts of a configuration
          • Backup and restore every setting in the same instance
      • OAuth2 Authorizations in Email This Issue
        • OAuth2 Client Credentials
        • Authorizing Email This Issue to access Gmail accounts
        • Authorizing Email This Issue to access Microsoft 365 accounts
        • Enabling OAuth2 Authorization in your Google Account
        • Enabling OAuth2 authorization in your Microsoft 365 account
        • Troubleshooting guides for Microsoft OAuth2 Connections
          • How to fix "Authorization Was Interrupted" error
          • How to fix "BAD User is authenticated but not connected" error
          • How to fix "401 Unauthorized" error
          • How to fix "key expires_in " error
          • How to fix "Need admin approval" error
      • Alerting via Webhooks
        • Webhooks
          • Configuring Slack to receive webhooks
          • Configuring OpsGenie to receive webhooks
        • Webhook execution logs
      • Email Security
    • Service management integration
    • JQL Functions
    • Top-level menu navigation
  • ☁️Server to Cloud Migration
    • Server to Cloud - Automatic Migration tool
    • Server to Cloud - Manual migration guide for Email This Issue
      • Overview of available features
      • Differences of the Server and Cloud user interface
      • Migrating Outgoing Settings
        • Migrating Templates
        • Migrating Notifications
        • Migrating Manual Email Defaults
        • Migrating Contexts
        • Migrating Canned Responses
        • Migrating Post Functions
        • Migrating Outgoing Mail Connections
      • Migrating Incoming Settings
        • Migrating Classic Mail Handlers
        • Migrating Next Generation Mail Handlers
        • Migrating Incoming Mail Connections
        • Migrating Incoming Mail Queue Settings
        • Migrating Incoming Mail Log Settings
      • Migrating Other Settings
        • Migrating OAuth2 Credentials
        • Migrating global default email settings
        • Migrating permissions for sending emails manually
        • Migrating recipient restrictions
  • ❓FAQ
    • FAQ
      • How to bypass workflow conditions
      • How to avoid email loops
      • How to control who to send emails to
      • How to customize Email From in outgoing emails
      • How to enable logging
      • How to install license keys
      • How to find out why the Email button is missing
      • How to obtain a community or non-profit license
      • How to prevent duplicate emails
      • How to remove old content from reply emails
      • How to send personalized emails to recipients
      • How to set up auto-reply or acknowledgment emails
      • How to track cases when you don't get any emails
      • How to view the log of incoming and outgoing emails
      • The iOS Mail app does not show attachments
      • How to route emails to projects
      • How to maintain email threads in Jira
      • How to fix issues with a corrupt index state
      • How to set polling interval for mail accounts manually
    • Tutorials
      • Configuring email approval
      • Customizing the email template used with manual emails
      • Enhance Jira Service Management with Email This Issue
      • Getting Started
      • Setting up an Email Help Desk
      • Setting up customized notifications
      • Setting up a Service Management with a Next-Gen Mail Handler
  • 🌪️Misc
    • Open Source Components
    • Pricing Updates
      • Pricing Update effective October 1st 2018
      • Pricing Update effective December 1, 2021
    • End of Support Policy
    • Security Advisories
      • Email This Issue Security Advisory 2020-02-18
    • Database Tables
    • Translations
  • 🆕Release Notes
    • Release notes
      • 9.x.x
        • 9.15.0 Jira 10 compatibility
        • 9.13.0 Improvements and Fixes
        • 9.11.0 Improvements and fixes
        • 9.10.0 Major improvements and fixes
        • 9.9.1 Improvements and fixes
        • 9.9.0.2 Major improvements and fixes
        • 9.8.0 Improvements and fixes
        • 9.7.0 Improvements and fixes
        • 9.6.0 Improvements and fixes
        • 9.5.0 Improvements and fixes
        • 9.4.0 Bugfixes
        • 9.3.3. Improvements and fixes
        • 9.3.2 Major improvements
        • 9.3.1 Automatic cloud migration
        • 9.2.2.1 Bugfixes
        • 9.2.2 Improvements and fixes
        • 9.2.1.3 Compatibility changes for Jira 9.0.0
        • 9.2.1 Major improvements
        • 9.2.0 Improvements and fixes
        • 9.1.1 Improvements and fixes
        • 9.1.0.1 Alerting and other major new features
        • 9.0.2 Bugfixes, next step in deprecating the Classic Mail Handler
        • 9.0.1 Minor improvement and fixes
        • 9.0.0 Major improvements
        • 9.12.0 Improvement and fixes
        • 9.17 Improvements and Fixes
        • 9.18.0 Improvements and fixes
      • 8.1.x
        • 8.1.3 Classic handler is deprecated, timezone support, bug fixes
        • 8.1.2 Important bug fixes
        • 8.1.1 Microsoft 365 OAuth2, improvements and fixes
        • 8.1.0 Microsoft 365 OAuth2, improvements and fixes
      • Up to 8.0.6
Powered by GitBook
On this page
  • Comparison of Mailbox Management in Jira and Email This Issue
  • Incoming Mail Connections
  • Search
  • Add a new Incoming Mail Connection with Password Authentication
  • Add a new Incoming Mail Connection with OAuth2 Authorization
  • Shared mailbox settings
  • Incoming Mail Connection attributes
  • Decide what to do after Emails are downloaded
  • Test Connections
  • How to use Incoming Mail Connections
  • Email Security
  • Enabling Incoming Mail Connections
  • Filtering the list

Was this helpful?

  1. Documentation
  2. Administration

Incoming Mail Connections

PreviousOutgoing Mail QueueNextIncoming Mail Queue

Last updated 1 year ago

Was this helpful?

SINCE VERSION 8.0.0

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.

Search

The mail connection list is searchable with the Search button on the top left part of the list. The filter search in the Name, Description, Host, Username fields.

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.

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.

The dropdown contains a pre-defined set of hostnames, which are globally available. If you have even more specific needs, please contact our support team.

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

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:

Incoming Mail Connection attributes

Attribute
Description
Applicable to Protocols
Mandatory

Name

Unique name of the IMAP or POP3 connection

IMAP/POP OAUTH2

Description

A longer description of the purpose of this connection

IMAP/POP OAUTH2

Protocol

Specifies the protocol to use when connecting the service. Values are:

  • IMAP

  • POP3

  • Google OAuth2

  • Microsoft OAuth2 (coming soon in version 8.1.1)

IMAP/POP OAUTH2

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.

OAUTH2

Encryption

Supported encryptions:

  • No encryption

  • SSL/TLS

  • STARTTLS

IMAP/POP

Host

The hostname or IP addresses of the IMAP or POP3 server or for Microsoft O365 OAuth2

IMAP/POP OAUTH2

Port

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).

IMAP/POP

Interval

The period in minutes the Incoming Mail Connections are connected to mailboxes.

IMAP/POP OAUTH2

Timeout

IMAP or POP3 connection timeout in milliseconds, valid value: 1-30000 ms. Leave blank or 0 for default (30000 ms).

IMAP/POP OAUTH2

Folder

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.

IMAP/POP OAUTH2

Username

Connection credentials.

IMAP/POP OAUTH2

Shared mailbox alias

Connection credentials.

IMAP/POP OAUTH2

Password

Connection credentials. Please note that the password should only contain ASCII-characters.

IMAP/POP

Decide what to do after Emails are downloaded

SINCE VERSION 8.1.1

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

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.

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):

Depending on the selected connection mode (and the underlying protocol) about the mailbox's current state, the exact number of 'new' messages (from the app's point of view) might not be possible to be determined within a reasonable amount of time. Consequently, the accuracy and confidence level of this estimation might vary in different use cases and situations.

The displayed message count may be affected by several factors, including but not restricted to the following:

  • whether it is a "brand new" or an "already known" mailbox for the app

  • the total number of (unread or all) messages within the mailbox

  • the number/ratio of known and new messages (stored message UIDs)

  • the number of already processed, but “manually reset” messages (being set unread again)

  • various mail server settings (session-level restrictions)

Moreover, it is also hard to verify the outcome in graphical email clients (Gmail/Outlook/etc. browser/app), as they may still keep track of read and deleted messages differently by hiding some details from the end user.

Despite all these considerations, the estimation can be classified as pretty much exact or at least as fair and reliable in most cases.

There is one notable exception though - POP3 connections, where the "mark as read" post-download action is selected. Here, both the accuracy and the confidence level of the estimation result may be extremely low. Nevertheless, we highly discourage you from using this unfortunate option (or rather combination) in real-world (i.e. production/production-like) scenarios, as the performance of the message download will also erode over time (as facing an ever-growing mailbox, where all the messages must be considered and handled as "potentially relevant" by design).

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.

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:

These Incoming Mail Connections cannot be used with Jira's built-in Incoming Mail Handlers, only with our app's .

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:

🤓
Authorize Email This Issue to access Gmail accounts
Authorize Email This Issue to Access Microsoft 365 Accounts
https://docs.microsoft.com/en-us/exchange/collaboration/shared-mailboxes/shared-mailboxes
Next Generation Mail Handlers
Overriding hostname for an OAuth2-based Microsoft365 IMAP connection
Shared mailbox settings for Incoming Mail Connection
Certificates after searching