# 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](helpdesk-email-channel.html).

* 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](mailbox-integration-issue-tracking.html).

> **Note: Email Notifications**
> The settings you encounter on the Mailbox Integration page are completely unrelated to the configuration that is used to deliver email notifications from YouTrack. To learn how to set up a connection to a mail service for delivering standard update notifications from YouTrack, see [Notifications](notification-settings.html).

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

1. [Set the system-wide polling frequency for connected mailboxes](#fetch-email).

2. [Import the trusted certificates for your mail server into YouTrack.](#import-trusted-certificates-mail-server)

3. [Connect to the mail service](#connect-to-mail-server).

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

Procedure: To specify an interval for retrieving email messages:

> **Tip:**
> Requires permissions: Low-level Admin Write

1. From the main navigation menu, select ![](https://resources.jetbrains.com/help/img/youtrack/2026.2/settings.svg) `Administration > Integrations > Mailbox Integration`.

2. 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:

```GENERIC
0 0/45 * * * ?
```

![YouTrack interface showing fetching interval.](https://resources.jetbrains.com/help/img/youtrack/2026.2/mailbox-integration-fetching-interval.png)

For IMAP mailboxes, the shortest possible interval is 2 minutes.

> **Note: Cron Expression Format**
> YouTrack evaluates cron expressions using the Quartz Job Scheduling Library. To ensure that your cron expressions are interpreted correctly:
>
>
>
> * Specify values for six fields (second, minute, hour, day of the month, month, day of the week), not five.
>
> * Specify the day of the week as a value between 1 and 7, where 1 represents Sunday. It also accepts three-letter abbreviations for SUN-SAT. Expressions that use values between 0 and 7 where both 0 and 7 represent Sunday will not be parsed as expected.

To learn more about the syntax for writing a cron expression, please refer to the [cron trigger tutorial](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html).

### Import Trusted Certificates from Your Mail Server

> **Note:**
> Mail servers that use unsecured protocols like IMAP may have an extension that enables [opportunistic TLS](https://en.wikipedia.org/wiki/Opportunistic_TLS). For security, YouTrack connects to a mail server over STARTTLS whenever it is available.

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.

Procedure: To enable a secure connection between YouTrack and your mail server:

> **Tip:**
> Requires permissions: Low-level Admin Write

1. Export the certificate and public key for your mail server as a DER-encoded file. These files use the .der, .cer, and .crt extensions.

2. From the main navigation menu, select ![](https://resources.jetbrains.com/help/img/youtrack/2026.2/settings.svg) `Administration > Server Settings > SSL Certificates`.

3. Click the Import trusted certificate button.

4. In the Import Trusted Certificate dialog, enter a name for the certificate.

5. Click the Choose file button and select the certificate file from your local directory.

![Import Trusted Certificate dialog with name and certificate fields.](https://resources.jetbrains.com/help/img/youtrack/2026.2/import-trusted-certificate.png)

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

> **Note:**
> The steps for performing this operation vary by mail server. Before you start, make sure you have selected the tab that corresponds to the mail server you want to use for this integration.

* For YouTrack Cloud instances, you can enable a built-in default mailbox configuration. This configuration processes messages sent to a dedicated email address associated with your YouTrack instance. With the default mailbox configuration, you don't need an external mail server, and the settings are predefined, so you don't need to configure anything. For details, see [YouTrack Cloud](#default-mailbox-configuration).

* For Gmail, there are special requirements for the account that you use to connect to the mail service. For details, see [Gmail](#smtp-settings-gmail-server).

* 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](#ms-exchange-online) or [Microsoft Exchange Server](#ms-exchange-server).

Gmail:

To send YouTrack notifications using a Gmail account, you need to generate and use an application-specific password (App Password). The Google account that you use for authentication 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.

To learn more about app passwords for Google accounts, please refer to the [Gmail Help](https://support.google.com/mail/answer/185833).

Procedure: To connect to Gmail mailbox:

> **Tip:**
> Requires permissions: Low-level Admin Write

1. From the main navigation menu, select ![](https://resources.jetbrains.com/help/img/youtrack/2026.2/settings.svg) `Administration > Integrations > Mailbox Integration`.

2. On the Mailbox Integration page, click the Connect with another mailbox link.

* The Mailbox settings are displayed in the sidebar.

![Mailbox Integration settings with the generic mail-server connection fields.](https://resources.jetbrains.com/help/img/youtrack/2026.2/connect-to-mail-server.png)

3. Enter values for the following settings:

| Setting | Description |
| --- | --- |
| Server type | Select the protocol that you want to use for the connection. YouTrack supports connections with Gmail over IMAP and IMAPS.    |
| 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.     > **Note:** > For integrations with Gmail, additional security requirements may apply. For details, see [Gmail](#smtp-settings-gmail-server).    |
| Password | Enter the app password for the account that you use to log in to the Gmail service. |

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

5. Click the Test connection button to verify the configuration. If the connection cannot be established, correct your settings and test the connection again.

6. Click the Add server button.

* The mailbox integration settings are saved.

IMAP/IMAPS:

Use the following instructions to configure a connection with a generic mail service.

Procedure: To connect to a generic mail service:

> **Tip:**
> Requires permissions: Low-level Admin Write

1. From the main navigation menu, select ![](https://resources.jetbrains.com/help/img/youtrack/2026.2/settings.svg) `Administration > Integrations > Mailbox Integration`.

2. On the Mailbox Integration page, click the Connect with another mailbox link.

* The Mailbox settings are displayed in the sidebar. ![Mailbox Integration settings with IMAP selected as the server type.](https://resources.jetbrains.com/help/img/youtrack/2026.2/connect-to-imap-mail-server.png)

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

4. 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](ssl-key-stores.html).   |
| 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. |

5. Click the Test connection button to verify the configuration. If the connection cannot be established, correct your settings and test the connection again.

6. Click the Add server button.

* The mailbox integration settings are saved.

Microsoft Exchange Online:

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](#register-client-app-microsoft-azure).

* Add the requisite API permissions to the client app. For details, see [Add the Required Permissions to the Client App](#add-permissions-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](#update-mailbox-integration-settings-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 Essentials section of a registered client application in Microsoft Azure.](https://resources.jetbrains.com/help/img/youtrack/2026.2/azure-client-app-essentials.png)

The client secret can be generated from the Certificates & secrets < Client secrets section.

![The Certificates & secrets section of a registered client application in Microsoft Azure.](https://resources.jetbrains.com/help/img/youtrack/2026.2/azure-client-app-secret.png)

To learn how to perform this setup, please follow the instructions in the [product documentation for Microsoft Azure](https://docs.microsoft.com/en-gb/azure/active-directory/develop/quickstart-register-app).

#### Add the Required Permissions to the Client App

Next, you need to add the following API permissions to the app:

* User.Read must be granted as a Delegated permission.

If you want the app to access mailboxes using Microsoft Entra application permissions, grant Mail.ReadWrite as an Application permission.

If you want to restrict the app to specific mailboxes using Exchange Application RBAC, do not grant Mail.ReadWrite in Microsoft Entra ID. In this setup, mailbox access is granted and scoped in Exchange Online.

The list of permissions can be found in the API permissions settings of the client app.

![The API permission settings of a registered client application in Microsoft Azure.](https://resources.jetbrains.com/help/img/youtrack/2026.2/azure-client-app-api-permissions.png)

If your setup uses Microsoft Entra application permissions and 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](https://learn.microsoft.com/en-gb/azure/active-directory/develop/quickstart-configure-app-access-web-apis#application-permission-to-microsoft-graph).

> **Warning: Restricting Access to Specific Mailboxes**
> The permissions specified here grant the application global permission to read and write messages in any mailbox on the server. If your organization uses Microsoft Exchange Online to host private mailboxes, you should take extra measures to protect the privacy and security of sensitive information.
>
>
>
> Use one of the following solutions:
>
>
>
> * Restrict application permissions to specific mailboxes using mail-enabled security groups and application policies in Microsoft Azure. For detailed instructions, refer to the documentation for [Microsoft Exchange Online](https://learn.microsoft.com/en-us/exchange/recipients-in-exchange-online/manage-mail-enabled-security-groups).
>
> * Use Role Based Access Control (RBAC) to grant specific permissions to the application and restrict the permission scope to a specific mailbox. When you use Exchange Application RBAC, do not also grant Mail.ReadWrite in Microsoft Entra ID, otherwise the broader application permission overrides the mailbox restriction. For more information, refer to the documentation for [Microsoft Exchange Online](https://learn.microsoft.com/en-us/exchange/permissions-exo/application-rbac).

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

Procedure: To connect to a Microsoft Exchange Online mailbox:

> **Tip:**
> Requires permissions: Low-level Admin Write

1. From the main navigation menu, select ![](https://resources.jetbrains.com/help/img/youtrack/2026.2/settings.svg) `Administration > Integrations > Mailbox Integration`.

2. On the Mailbox Integration page, click the Connect to another mailbox link.

* The Mailbox settings are displayed in the sidebar. ![Mailbox Integration settings with Microsoft Graph selected as the server type.](https://resources.jetbrains.com/help/img/youtrack/2026.2/connect-to-ms-online-mail-server.png)

3. For the Server type setting, select Microsoft Exchange Online.

* The integration is updated to show specific settings for this server type.

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

5. 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](ssl-key-stores.html).   |
| 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. |

6. To verify that YouTrack is able to establish a connection with the mail server, click the Test connection button.

7. If the test is successful, click the Add server button.

* The mailbox integration settings are saved.

Microsoft Exchange Server:

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](https://davmail.sourceforge.net/serversetup.html). 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.

Procedure: To connect to a mail service:

> **Tip:**
> Requires permissions: Low-level Admin Write

1. From the main navigation menu, select ![](https://resources.jetbrains.com/help/img/youtrack/2026.2/settings.svg) `Administration > Integrations > Mailbox Integration`.

2. On the Mailbox Integration page, click the Connect with another mailbox link.

* The Mailbox settings are displayed in the sidebar. ![Mailbox Integration settings with Exchange Web Services selected as the server type.](https://resources.jetbrains.com/help/img/youtrack/2026.2/connect-to-ms-mail-server.png)

3. 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 IMAP/IMAPS protocols.     > **Note:** > To connect to a Microsoft Exchange Server mailbox, you must first configure your mail service to support either IMAP/IMAPS as described [here](#ms-exchange-server). > > > > To ensure that the protocol is recognized correctly, enable the MS Exchange compatibility mode checkbox.    |
| 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.     > **Note:** > For Microsoft Exchange Server, the mailbox integration supports connections to shared mailboxes. Enter the username for any user who is a member of the shared mailbox. Use the syntax `email address/shared mailbox name`. > > > > To ensure that the authorization request handled correctly, enable the MS Exchange compatibility mode checkbox below the Protocol setting.    |
| Password | Enter the password for the account that you use to log in to the mail service. |

4. 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](ssl-key-stores.html).   |
| 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. |

5. Click the Test connection button to verify the configuration. If the connection cannot be established, correct your settings and test the connection again.

6. Click the Add server button.

* The mailbox integration settings are saved.

YouTrack Cloud:

If you don't have an external mailbox, you can still benefit from the mailbox integration and use a default email address provided by YouTrack.

For each YouTrack Cloud instance, YouTrack creates a default mailbox. When the default mailbox configuration is enabled, you can share the address of this mailbox with other people. YouTrack processes messages sent to this address according to the mailbox integration rule settings.

The default email address is `instancename@youtrack.cloud` where `instancename` is the name of your YouTrack.

Since you don't have access to the actual mailbox with this type of mailbox configuration, if you have any issues, [submit a request](https://youtrack-support.jetbrains.com/hc/en-us) to the YouTrack support and ask for assistance.

Procedure: To connect to a mail service:

> **Tip:**
> Requires permissions: Low-level Admin Write

1. From the Administration menu, select `Integrations > Mailbox Integration`.

2. On the Mailbox Integration page, click the Connect with another mailbox link.

3. Click the Add server button.

* A connection to the default mail service for YouTrack Cloud is added to your instance.

## 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 mail server requires a secure connection. | Import the certificate for your mail server into YouTrack. For instructions, see [SSL Certificates](ssl-certificates.html). |
| Your SSL certificate for the mail server has expired. | Renew and import the updated certificate into YouTrack. For instructions, see [SSL Certificates](ssl-certificates.html). |
| 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:       * Make sure your Exchange mailbox is configured to use either POP/POPS or IMAP/IMAPS and authenticate over SMTP as described for [Microsoft Exchange Online](#ms-exchange-online) or [Microsoft Exchange Server](#ms-exchange-online).    * Verify that the Protocol setting in the mailbox integration matches the protocol that is enabled for your Exchange mailbox.    * Enable the MS Exchange compatibility mode checkbox.     If you are still unable to establish a connection, [submit a support request](https://youtrack-support.jetbrains.com/hc/en-us).   |

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 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](ssl-certificates.html). 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. |