Mailbox Integration
The Mailbox Integration lets you set up a connection between YouTrack and a mail server. Once this connection has been established, you can configure additional settings that transform incoming email messages into tickets, issues, and comments in YouTrack. Comments posted to tickets and issues in YouTrack are delivered through the mail server as replies to the original email message.
The settings and basic behavior vary based on the type of YouTrack project where the integration is enabled.
In helpdesk projects, a mailbox integration is used as the basis for processing customer requests in an email channel. To learn more about this setup, see Email.
In a standard project for issue tracking, the integration transforms incoming messages into issues and comments according to the rules that are configured for the connected mail service. These rules are configured directly in the Mailbox Integration settings. To learn more about this setup, see Mailbox Integrations with Standard Issue Tracking Projects.
Enable the Mailbox Integration
To process incoming email messages in YouTrack, you must first enable and configure the Mailbox integration.
This procedure requires the following steps:
Set the system-wide polling frequency for connected mailboxes.
Import the trusted certificates for your mail server into YouTrack.
Set the System-wide Polling Frequency for Connected Mailboxes
YouTrack retrieves email messages from the specified mail services according to a schedule. The default interval is every hour. You can change the schedule to a predefined interval or specify a custom interval with a cron expression. The schedule is not set independently for multiple mail services. The same schedule is applied to all mail services that are integrated with the YouTrack server.
To specify an interval for retrieving email messages:
From the Administration menu, select .
From the System-wide polling frequency menu, select a pre-configured time interval. To specify another time interval, select Custom and enter a cron expression. For example, to pull fresh data every 45 minutes, every day, use the following expression:
0 0/45 * * * ?
For IMAP mailboxes, the shortest possible interval is 2 minutes.
To learn more about the syntax for writing a cron expression, please refer to the cron trigger tutorial.
Import Trusted Certificates from Your Mail Server
Your mail server may require that you establish a secure connection over SSL. Before you can add your hosted server to YouTrack, you may need to import its SSL certificate.
If your mail server has a valid certificate that is signed by a well-known certificate authority (CA), the public key and certificate are already stored in the web browser. You should be able to connect to your mail server without importing its SSL certificate.
If the certificate for your mail server is self-signed, you need to import the certificate and public key to establish a secure connection.
To enable a secure connection between YouTrack and your mail server:
Export the certificate and public key for your mail server as a DER-encoded file. These files use the .der, .cer, and .crt extensions.
From the Administration menu, select .
Click the Import trusted certificate button.
In the Import Trusted Certificate dialog, enter a name for the certificate.
Click the Choose file button and select the certificate file from your local directory.
Click the Import button.
The certificate for your mail server is added to YouTrack.
Connect to a Mail Service
To enable the integration, you need to connect to one or more mail servers.
For Gmail, there are special requirements for the account that you use to connect to the mail service. For details, see Gmail.
For Microsoft Exchange Server and Microsoft Exchange Online (Office 365) mailboxes, additional setup is required. To configure your mail service to be compatible with this integration, read and follow the instructions for Microsoft Exchange Online or Microsoft Exchange Server.
Google accounts have settings that restrict access to third-party applications that use less secure sign-in technology. By their definition, this applies to connections that authenticate with a username and password, which are vulnerable to hijacking.
The setup requirements are based on the current setting for managing less secure apps. The requirements apply to the Google account that you use to authenticate with the Gmail service.
If you're connecting with a Google account that you manage yourself, generate an application-specific password (App Password) in your Google account and use it for authentication. Leave the option to enable access for less secure apps in your Google account Off.
App Passwords can only be used with accounts that have 2-Step Verification turned on.
If you use a Google account that is managed by your organization as part of Google Workspace, make sure that the option to Disable access to less secure apps is switched on.
The Google account that you store in the mailbox integration settings must have 2-Step Verification enabled. To connect to the Gmail service with this account, generate an application-specific password in your Google account.
For the Username, enter the username for your Google account.
For the Password, enter an application-specific password that you generated in Google.
While you may still allow access to less secure apps, Google has indicated that it will eventually discontinue support for this type of authentication. We strongly encourage you to enable 2-Step Verification and use an App Password to authenticate with the Gmail service.
To connect to Gmail mailbox:
From the Administration menu, select .
On the Mailbox Integration page, click the Add New Mail Server link.
The Mailbox settings are displayed in the sidebar.
Enter values for the following settings:
Setting
Description
Server type
Select the protocol that you want to use for the integration. Gmail supports the POP/POPS and IMAP/IMAPS protocols.
Host
Enter the URL of the mail service. For example,
imap.gmail.com.Port
Enter the port that the mail service listens to. The default port is set automatically when you select the mail server protocol.
Username
Enter the username of the account that authorizes access to the mail service.
Password
Enter the password for the account that you use to log in to the Gmail service.
Expand the Advanced settings section and configure the following optional settings:
Setting
Description
SSL key
For integrations with Gmail, you can ignore this setting. Connections with the Gmail service are automatically authenticated using TLS.
Connection timeout
Set the maximum amount of time to wait for complete data transfer from the mail service before closing the connection. The default value is set to 60 seconds.
Socket timeout
Set the maximum amount of time to wait for a response from the mail service before disconnecting the socket. The default value is set to 60 seconds.
Click the Test connection button to verify the configuration. If the connection cannot be established, correct your settings and test the connection again.
Click the Add server button.
The mailbox integration settings are saved.
Use the following instructions to configure a connection with a generic mail service.
To connect to a generic mail service:
From the Administration menu, select .
On the Mailbox Integration page, click the Add New Mail Server link.
The Mailbox settings are displayed in the sidebar.
Enter values for the following settings:
Setting
Description
Server type
Select the protocol that is used by the mail server. The mailbox integration supports the POP/POPS and IMAP/IMAPS protocols.
Host
Enter the URL of the mail service. For example,
mail.server.com.Port
Enter the port that the mail service listens to. The default port is set automatically when you select the mail server protocol.
Username
Enter the username of the account that authorizes access to the mail service.
Password
Enter the password for the account that you use to log in to the mail service.
Expand the Advanced settings section and configure the following optional settings:
Setting
Description
SSL key
If your mail server requires client SSL authentication, select the SSL key that identifies your YouTrack server from the list.
The list only displays SSL keys that have already been imported into YouTrack. To learn how to generate and upload SSL keys, see SSL Keys.
Connection timeout
Set the maximum amount of time to wait for complete data transfer from the mail service before closing the connection. The default value is set to 60 seconds.
Socket timeout
Set the maximum amount of time to wait for a response from the mail service before disconnecting the socket. The default value is set to 60 seconds.
Click the Test connection button to verify the configuration. If the connection cannot be established, correct your settings and test the connection again.
Click the Add server button.
The mailbox integration settings are saved.
An integration with Microsoft Exchange Online (also commonly known as Exchange Online, Office 365, or Microsoft 365) requires that you perform the following actions:
First, you need to register an application in the Microsoft Azure portal. This gives you access to a client ID and client secret that you will use to re-connect to the Exchange Online service. For more information, see Register a Client Application in Microsoft Azure.
Add the requisite API permissions to the client app. For details, see Add the Required Permissions to the Client App.
Configure the configuration for the Mailbox integration in YouTrack to use the settings for integrations with Microsoft Exchange Online. For instructions, see Update the Mailbox Integration Settings in YouTrack.
Register a Client Application in Microsoft Azure
This setup requires that you meet the following prerequisites:
A valid license for Microsoft Exchange Online.
Administrative access to Microsoft Azure Active Directory (AD).
To complete the migration, you will need to obtain the following information from the Microsoft platform:
The email address of the mailbox where you want to retrieve incoming messages. This mailbox must belong to the same Azure AD service where you register the app.
The Application (client) ID of the app that is registered in the Microsoft Azure portal.
The Directory (tenant) tenant ID of your Azure Active Directory tenant organization.
A client secret that you created for the registered app.
The Application (client) ID and Directory (tenant) ID can be found in the Essentials section of the client application as shown below.
The client secret can be generated from the Certificates & secrets < Client secrets section.
To learn how to perform this setup, please follow the instructions in the product documentation for Microsoft Azure.
Add the Required Permissions to the Client App
Next, you need to add the following API permissions to the app:
Mail.ReadWrite must be granted as an Application permission.
User.Read must be granted as a Delegated permission.
The list of permissions can be found in the API permissions settings of the client app.
If you are logged in under an administrator account (as listed in the prerequisites), you can grant the application permission Mail.ReadWrite yourself. If not, you will need to ask an administrator to grant admin consent to the permissions configured for the application.
To learn how to configure permissions for a client app, please follow the instructions in the product documentation for Microsoft Azure.
Update the Mailbox Integration Settings in YouTrack
Once you have collected the required information from the Microsoft platform, you can configure the settings for your Mailbox integration in YouTrack.
To connect to a Microsoft Exchange Online mailbox:
From the Administration menu, select .
On the Mailbox Integration page, click the Add New Mail Server link.
The Mailbox settings are displayed in the sidebar.
For the Server type setting, select Microsoft Exchange Online.
The integration is updated to show specific settings for this server type.
Enter values for the following settings:
Setting
Description
Mailbox address
Enter the email address where the integration currently retrieves incoming messages.
Tenant ID
Enter the Directory (tenant) ID of the Azure Active Directory tenant organization.
Client ID
Enter the Application (client) ID for the registered client application in Microsoft Azure.
Client secret
Enter the value for the secret that you generated for the client app in Microsoft Azure.
Expand the Advanced settings section and configure the following optional settings:
Setting
Description
SSL key
If your mail server requires client SSL authentication, select the SSL key that identifies your YouTrack server from the list.
The list only displays SSL keys that have already been imported into YouTrack. To learn how to generate and upload SSL keys, see SSL Keys.
Connection timeout
Set the maximum amount of time to wait for complete data transfer from the mail service before closing the connection. The default value is set to 60 seconds.
Socket timeout
Set the maximum amount of time to wait for a response from the mail service before disconnecting the socket. The default value is set to 60 seconds.
To verify that YouTrack is able to establish a connection with the mail server, click the Test connection button.
If the test is successful, click the Add server button.
The mailbox integration settings are saved.
The mailbox integration in YouTrack only supports POP/POPS and IMAP/IMAPS. The default protocol for Microsoft Exchange, MAPI, is not supported. If you want to connect to a Microsoft Exchange, you have two options:
Enable and configure either POP or IMAP in the Microsoft Exchange, then configure the authenticated SMTP settings. With these mail connectors enabled, you can follow the instructions below and establish a connection.
Pay attention to the special instructions for Microsoft Exchange mailboxes.
Establish a connection through an intermediate gateway server. This lets you connect to the Exchange Server with POP/IMAP and SMTP disabled. The DavMail exchange gateway, for example, converts proprietary Exchange formats into email protocols that YouTrack understands. For setup instructions, refer to the DavMail Gateway documentation.
With this setup, follow the instructions below to establish a connection to the gateway server.
For Microsoft Exchange Server, the mailbox integration supports connections to shared mailboxes. You can use the username and password of any user who is a member of the shared mailbox to authenticate.
To connect to a mail service:
From the Administration menu, select .
On the Mailbox Integration page, click the Add New Mail Server link.
The Mailbox settings are displayed in the sidebar.
Enter values for the following settings:
Setting
Description
Server type
Select the protocol that is used by the mail server. The mailbox integration supports the POP/POPS and IMAP/IMAPS protocols.
Host
Enter the URL of the mail service. For example,
mail.exchange.com.Port
Enter the port that the mail service listens to. The default port is set automatically when you select the mail server protocol.
Username
Enter the username of the account that authorizes access to the mail service.
Password
Enter the password for the account that you use to log in to the mail service.
Expand the Advanced settings section and configure the following optional settings:
Setting
Description
SSL Key
If your mail server requires client SSL authentication, select the SSL key that identifies your YouTrack server from the list.
The list only displays SSL keys that have already been imported into YouTrack. To learn how to generate and upload SSL keys, see SSL Keys.
Connection Timeout
Set the maximum amount of time to wait for complete data transfer from the mail service before closing the connection. The default value is set to 60 seconds.
Socket Timeout
Set the maximum amount of time to wait for a response from the mail service before disconnecting the socket. The default value is set to 60 seconds.
Click the Test connection button to verify the configuration. If the connection cannot be established, correct your settings and test the connection again.
Click the Add server button.
The mailbox integration settings are saved.
Troubleshooting
If you experience problems setting up the mailbox integration, see if any of the following conditions apply.
Condition — You are unable to establish a connection to the mail service.
Cause | Solution |
|---|---|
The external service is unavailable. | Verify that your mail service is running. |
The connection is blocked by a firewall. | Open the ports in the firewall that are used by YouTrack and the mail service. |
The connection to the external service is blocked by the proxy server. You are trying to connect over the wrong port. | Set the system properties for your server that let YouTrack connect to other services through the proxy server. For instructions, see Proxy Configuration. |
The mail server requires a secure connection. | Import the certificate for your mail server into YouTrack. For instructions, see SSL Certificates. |
Your SSL certificate for the mail server has expired. | Renew and import the updated certificate into YouTrack. For instructions, see SSL Certificates. |
You are trying to connect to a Microsoft Exchange mailbox, and there are configuration problems in either the mail service or YouTrack. | Check the following setup requirements:
If you are still unable to establish a connection, submit a support request. |
Condition — You are unable to establish a connection to your mail server over an unsecured protocol. YouTrack returns the error bad_request.
Cause | Solution |
|---|---|
Your IMAP or POP3 server uses an extension that enables STARTTLS. YouTrack requires a secure connection to your mail server. | Import the SSL certificate for your mail server into YouTrack. For instructions, see SSL Certificates. If both YouTrack and your mail server run on a private computer network, you can generate and import a self-signed SSL certificate for your mail server. |