Mailbox Integration

New Issues

If YouTrack cannot find any values that associate an incoming message with an existing issue, a new issue is created. YouTrack uses the following information from an email message to create a new issue:

• The message subject is copied to the issue summary.

• The message body is copied to the issue description.

• The mailbox rule that processes the email message determines which user is set as the reporter. The reporter can either be the message author or a default user.

Like any issue that is created manually, YouTrack assigns the issue an ID in the selected project.

Comments

When YouTrack detects that an incoming message is related to an existing issue, the body of the message is added to the issue as a comment. YouTrack matches an incoming message to an existing issue under the following conditions:

• The values for the message-id/in-reply-to properties in the message header match a previously processed email message. This is a standard method of parsing MIME-encoded messages. YouTrack uses these values to thread comments when a recipient replies to notifications that are sent when an issue is created or updated in the project.

  If you move an issue to another project, the reply to a related message is processed as a new issue in the connected project, not as a comment in the original issue.

• The message subject contains the ID of an issue in the same project.

Related Issues

In situations where the subject of an incoming message matches the summary of an existing issue, but the message does not contain any of the values that associate it with an existing issue a new issue is created. YouTrack processes these messages as follows:

• The prefixes that are added to forwarded messages and replies (FW:, RE:) are ignored.

• If the option in the mailbox rule is enabled, text that is set in square brackets is also ignored.

• YouTrack creates an issue and sets the message subject (minus the text strings that are ignored) as the issue summary.

• YouTrack finds the issue with the same summary that has the lowest ID number and adds a relates to link to it.

Configure Your Project

Before you start, create a project or configure an existing project to manage issues that are created by the mailbox integration. Later in this setup, you create a mailbox rule that references the project.

To configure a project for use with the mailbox integration, set the From address to the email address that you want to use to send emails. This setting overrides the global From address that is used for generic notifications. Setting this value in your project lets you manage incoming and outgoing messages with a dedicated email address.

You also have the option to set the Reply-to address for notifications in your project. Use this setting when, for example, the address that you use to send email notifications cannot receive replies.

To set the email addresses for an existing project:

1. Click the Projects link in the header.

2. Select the project from the list.

3. Click the Edit project link.

   • The Edit Project page opens.

4. In the From address input field, enter the email address that you want to use to send emails.

5. Optionally, enter the email address that you want to receive replies in the Reply-to address field.

Set the Schedule for Fetching Email Messages

YouTrack fetches email messages from the specified mail servers 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 servers. The same schedule is applied to all mail servers that are integrated with the YouTrack server.

To specify an interval for fetching email messages:

1. In the Integrations section of the Administration menu, select Mailbox Integration.

2. From the Fetching interval drop-down 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 details about cron expressions format, 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:

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. In the Server Settings area of the Administration menu, select 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.
   

   

6. Click the Import button.

   • The certificate for your mail server is added to YouTrack.

Connect to a Mail Server

To enable the integration, you need to connect to one or more mail servers.

• For mail servers that use POP/POPS or IMAP/IMAPS, follow these instructions.

• For Microsoft Exchange and Office 365 mailboxes, additional setup is required. Read the instructions that follow and configure your mail service to be compatible with this integration.

To connect to a mail server:

1. On the Mailbox Integration Settings page, click the Add New Mail Server link.

   • The Mailbox dialog opens in the sidebar.

     

2. Enter values for the following settings:

   Setting	Description
   Protocol	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 server. For example, mail.jetbrains.com.
   Port	Enter the port that the mail server listens to. The default port is set automatically when you select the mail server protocol.
   Login	Enter the username of the account that authorizes access to the mail server.
   Password	Enter the password of the login user account.

3. Expand the Advanced settings section and configure the following optional settings:

   Setting	Description
   SSL Key	If your mailbox supports a secure connection, select an SSL Key from the drop-down list. The SSL Key must be imported into YouTrack. For instructions, see SSL Keys.
   Connection Timeout	Set the maximum amount of time to wait for complete data transfer from the mail server 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 server before disconnecting the socket. The default value is set to 60 seconds.

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

5. Click the Save button.

   • The mailbox integration settings are saved.

Repeat these steps to add connections to additional mail servers.

Define Mailbox Rules

Now that you have connected YouTrack to a mail server, configure the rules for processing incoming email messages.

Mailbox rules are processed sequentially.

• If a message matches the filter that is defined in the first rule, it is processed according to the instructions that are defined in this rule. The message is not considered for processing by any subsequent rules.

• If the message does not match the filter that is defined in the first rule, it is evaluated against the criteria for the second rule, and so on.

• When a message does not match any filters, an internal record is created to register that the message was received. No further action is taken. The message is still considered to have been processed and is deleted from the mail server if the corresponding option is enabled in the mailbox rule.

You can create multiple mailbox rules that process messages in different ways. For example, you create a rule that scans the message body for words like "overdue" and "urgent" and automatically set the priority of the issue. You can then create additional rules to process the messages that don't contain these words.

To define a mailbox rule:

1. On the Mailbox Integration Settings page, click the Add Mailbox Rule button.

   • The Rule dialog opens in the sidebar.

     

2. Enter values for the following settings:

   Setting	Description
   Mailbox	Select the mailbox from which YouTrack fetches email messages.
   Project	Select which YouTrack project is assigned to issues that are created from incoming email messages.
   Maintainer	Select the username of the user who is responsible for the integration. The maintainer receives notifications when a command is unsuccessful or the issue reporter cannot be resolved. By default, the user who creates the rule is set as the maintainer.

3. Click to expand the Filter settings.

   These settings determine which emails should be fetched from the mail server. These settings are optional. If you want to process all incoming emails in YouTrack, continue with the next step.

   

   Enter values for the settings that are displayed in this section of the new rule:

   Setting	Description
   Folder	Select a folder to fetch only email messages that are delivered to this folder. If you don't select a folder, the integration fetches all email messages from the server except messages that have been permanently deleted. This includes messages in the sent, spam, and trash folders. For this reason, we strongly recommend that you select a folder, for example, the Inbox.
   'To' address	Enter an email address to fetch only email messages that are sent to this address. If you set a value here, use the same email address as the Project 'from' address in the project that is set as the Project for this mailbox rule. Otherwise, replies to messages that are sent by the mailbox integration are not added to issues as comments. To process all email messages in the specified folder, leave this field empty.
   Do not discard the contents of square brackets	Enable to include text that is set in square brackets in the issues and comments that are processed by YouTrack.
   Ignore auto replies	Enable to ignore email messages that are sent as automatic replies to messages that are sent from the YouTrack server. This setting prevents you from adding comments to issues when you receive automated out-of-office replies.
   Filter messages by patterns	Enter a pattern to search for in the message subject or text. You can write the patterns as regular expressions. If the pattern is detected in the message subject or text, the email message is ignored. Enter multiple patterns on separate lines in the input field.

4. Click to expand the Reporter settings. These settings define which user is set as the reporter for each issue that is processed from an incoming email message.

   

   Select one of the following options:

   Option	Description
   Set email sender as reporter. If no such user found in YouTrack, create new account for sender	YouTrack tries to find a user account with an email address that matches the author of the email message. If an existing account is not found, a new user account is created. Credentials for accessing YouTrack are sent to the author in the notification message that is sent when the issue is created.
   Set email sender as reporter. If no such user found in YouTrack, set default user as reporter	YouTrack tries to find a user account with an email address that matches the author of the email message. If an existing account is not found, a default user account is set as the reporter. Select an existing user account from the Default user drop-down list.
   Always set predefined user as reporter	When enabled, YouTrack automatically sets the specified user as the reporter for all issues that are created from incoming email messages.

5. Click to expand the Postprocessing settings. These settings define how YouTrack handles issues and comments that are created from incoming email messages. These settings are optional. If you don't want to automatically update issues that are processed by YouTrack, continue with the next step.

   

   Enter values for the settings that are displayed in this section of the new rule:

   Setting	Description
   Apply command to new issues	Enter a command to apply automatically to all issues that are created from incoming email messages. You can insert placeholders that reference values that are stored in the email message. For example: for [user] fromMail ${from} This command applies the following changes to any issue that is created from an incoming email message The issue is assigned to the specified user. The value for the custom field fromMail is set to the email address of the message author. For details, see Placeholders.
   Apply command on new comment	Enter a command to apply automatically when a comment is added to an issue from an incoming email message. You can also use placeholders in these commands. For details, see Placeholders.
   Add recipients as watchers	Enable to add users whose email addresses are included in the To: and CC: fields of the email message as watchers for the issues that are created from the incoming email message.
   Delete fetched messages from mailbox	Enable to delete all messages from the mail server after the corresponding issues have been created in YouTrack.
   Original timestamps (IMAP only)	Enable to set the creation date of the issue or comment to the timestamp of the original email message. Otherwise, the creation date is set to the date and time when the email message was processed by YouTrack.
   Prefer plain text for issue description when available	Enable to use the plain-text version of the message for the issue description whenever the incoming message contains a plain-text version of the email. If a plain text version is not available, the content from the HTML version of the message is wrapped {html} tags, formatted in YouTrack Wiki syntax, and used for the issue description instead.

6. Click the Save button.

   • The settings for the mailbox rule are saved.