YouTrack Server 2024.1 Help

Mailbox Integrations with Standard Issue Tracking Projects

The primary purpose of a mailbox integration is to support the transformation of email messages into tickets in a helpdesk project. However, this feature is only supported starting from YouTrack 2023.1. In earlier YouTrack versions, it was possible to set up mailbox integrations with standard projects for issue tracking and use these projects to support basic help desk interactions and process external email feedback.

While it is still possible to configure a mailbox integration for a standard project, advanced features that are exclusive to helpdesk projects are not available. Most importantly, helpdesk projects allow for an unlimited number of reporters. In a standard project, every user who submits a support request must have a registered user account.

A legacy setting for mailbox integrations gave you the option to designate a predefined reporter for all issues that were created using the mailbox integration. This meant an unlimited number of users could submit support requests to a help desk, but the process for handling and sending email replies relied on complex workflows. Existing mailbox integrations that have been configured to create issues using a predefined account as the reporter continue to work as expected. The ability to enable this configuration option for new mailbox integrations requires that the optional Configurable Reporters for Mailbox Integrations feature is enabled system-wide. To learn more, see System-wide Features.

Message Processing

This integration pulls email messages from an external mail service. Each message is parsed and analyzed by YouTrack. The messages are processed according to the mailbox rules that are defined for the project.

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.

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

Attachments

In email replies that are generated when comments are added to the issue in YouTrack, links are generated for new files that are attached to the issue or comment. These links are signed by the user who attached the files and provide direct access to the attachments. The recipient of the email reply can open and view these attachments without logging in to YouTrack.

To learn more about signed links for issue attachments, see Links to Issue Attachments.

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 Do not discard the contents of square brackets option in the mailbox rule is deselected, text in the subject line of the email message 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.

Prerequisites

Before you can enable a mailbox integration for a specific project, you need to have set up a connection to process incoming email messages from at least one mail server. For specific instructions, see Enable the Mailbox Integration.

Mailbox Integration Setup

To process incoming email messages as issues in YouTrack, you must first enable and configure the mailbox integration.

This procedure requires the following steps:

  1. Configure the project that you want to use to manage issues that are created by the integration.

  2. Define the rules that are applied to incoming email messages.

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.

Set Email Addresses for 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. In the right side-panel of the project page, click the Notifications link in the Administration section.

    • The Edit Project page opens with the Notifications tab selected.

    Notifications tab in the project settings
  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.

Customize the Delimiter for Replies

When you are done setting up mailbox integration for the project, YouTrack automatically enables a default delimiter for the replies. It helps the mailbox integration transform replies into comments with greater precision.

If a user writes an email reply and puts their text above the delimiter line, YouTrack will then show only the latest reply and collapse the rest of the thread in a comment. Replying above the delimiter lets you keep only the relevant information in the YouTrack comments.

The delimiter text is appended to the beginning of each reply that your team members post as a comment in the project integrated with a mailbox. The default delimiter text reads Please enter your reply above this line, and it is localized to the language of your YouTrack if you change the locale. If you customize the delimiter text, it will remain the same regardless of the YouTrack language.

To disable the delimiter, open the Notifications tab in the Edit Project page and disable the Use delimiter for replies option.

To change the text of the delimiter, enter the new text in the Delimiter text field.

Delimiter for the replies

Define Mailbox Rules

Now that you have connected YouTrack to a mail service, you can configure 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 service 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 page, click the New mailbox rule button.

    • The settings for a new mailbox rule are displayed in the sidebar.

      new mailbox rule
  2. Enter values for the following settings:

    Setting

    Description

    Mailbox

    Select the mailbox where you want to retrieve and process email messages.

    Project

    Select the YouTrack project where you want to create issues from incoming email messages.

    Administrator

    Select the username of the user who is responsible for the integration. The administrator receives notifications when a command is unsuccessful or the issue reporter cannot be resolved. By default, the user who creates the rule is selected automatically.

  3. Click to expand the Filters section.

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

    mailbox rule filter options

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

    Setting

    Description

    Folder

    Choose which folder you want to use as a source for processing incoming email messages. If you select a folder, messages that are delivered to the selected folder and its subfolders are processed.

    If you don't select a folder, the integration retrieves all email messages from the service 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.

    Recipient address

    Enter an email address to retrieve only email messages that are sent to this address. When used, YouTrack only applies this mailbox rule to messages that are sent directly to the specified recipient or sent as a carbon copy (as CC or BCC).

    If you set a value here, use the same email address as the 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.

    Discard the contents of square brackets

    Use this option to determine whether to include text that is set in square brackets in the issues that are processed by YouTrack. This option only applies to text in the subject line of an email message.

    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

    Enable to filter incoming emails containing pattern matched strings in the subject, body, or both from becoming helpdesk tickets.

    Select the message part of the email:

    • Subject - The pattern matches against strings within the subject of incoming emails.

    • Body - The pattern matches against strings within the body of incoming emails.

    • Subject and Body - The pattern matches against strings within the subject and body of incoming emails.

    Select the condition:

    • Contains - Incoming emails containing strings that match the pattern are filtered out.

    • Does not contain - Incoming emails that do not contain strings that match the pattern are filtered out.

    Enter a pattern to search for within incoming emails. You can write the patterns as regular expressions. Incoming emails meeting the conditions of the pattern filter are 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.

    mailbox rule reporter options

    Select one of the following options:

    Option

    Description

    Set email sender as reporter. If the sender email doesn't match an existing YouTrack account, create a new account.

    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 the sender email doesn't match an existing YouTrack account, use a default user account as the 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 use a predefined default user account as the reporter

    When enabled, YouTrack automatically sets the specified user as the reporter for all issues that are created from incoming email messages.

    Use the Default user setting to specify an existing user account.

  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.

    mailbox rule postprocessing options

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

    Setting

    Description

    Command for new issues and tickets

    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.

    If you need to apply several commands at once, enclose each placeholder in quotation marks. For example: toMail "${to}" fromMail "${from}". Without quotation marks, everything after the first placeholder is parsed as part of the same value.

    For details, see Placeholders.

    Command for new comments

    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.

    If you need to apply several commands at once, enclose each placeholder in quotation marks. For example: toMail "${to}" fromMail "${from}". Without quotation marks, everything after the first placeholder is parsed as part of the same value.

    For details, see Placeholders.

    Delete processed email messages

    Enable to delete all messages from the mail service after the corresponding issues have been created in YouTrack.

    Use 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 descriptions

    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 the plain-text version is not available, the content from the HTML version of the message is wrapped in HTML tags, stored in Markdown syntax, and used for the issue description instead.

  6. If you want to process email messages that have already been delivered to the connected mailbox, enable the Also process previously delivered messages option at the bottom of the form.

  7. Click the Add rule button.

    • The settings for the mailbox rule are saved.

    • In the settings of the target project, you can now customize the text of the delimiter that would appear in the replies to users sent by the members of your team.

Placeholders

You can use placeholders in the Postprocessing settings of a mailbox rule. These placeholders reference attributes in the original email message. The placeholder is replaced with the corresponding value in the message when it is processed by YouTrack. The following placeholders are available:

Placeholder

Description

${from}

The email address of the message author.

${from name}

The sender name of the message author.

${reply-to}

The value that is stored in the Reply-To: field of the email message header. This is the email address that is automatically inserted into the To: field when a recipient replies to an email message.

${to}

The email addresses of all message recipients that are entered in the To: field of the email message.

${cc}

The email addresses of all message recipients that are entered in the CC: field of the email message.

${bcc}

The email addresses of all message recipients that are entered in the BCC: field of the email message.

If you need to apply several commands containing placeholders in one setting, enclose each placeholder in quotation marks. For example: toMail "${to}" fromMail "${from}". Without quotation marks, everything after the first placeholder is parsed as part of the same value.

Troubleshooting

If you experience problems setting up the mailbox integration, see if any of the following conditions apply.

Condition — Incoming email messages are not converted into issues in YouTrack.

Cause

Solution

The user that is set as the reporter for issues that are processed from incoming email messages does not have permission to create issues in the project.

Check the Reporter settings for your mailbox rules.

  • If you set the email sender as the reporter, grant a Reporter role to either the All Users or the Registered Users groups for the project that is connected to the mailbox.

  • If you set a default or predefined user as the reporter, grant this user a Reporter role in the project that is connected to the mailbox.

Condition — Incoming email messages are converted into issues in YouTrack. Incoming replies are not added as comments.

Cause

Solution

The From address in the project settings uses an email address that is not processed by the mailbox rule or is not set. New issues are created from messages that are sent to the mail service, but replies to incoming messages are sent from another address. Replies to these messages are not sent to the mail service that is configured for the mailbox integration.

Set the From address for the projects that are selected in your mailbox rule settings to an address that is processed by the mailbox integration.

Check the Filter settings for your mailbox rule. If you set the 'To' address, use the same email address as the From address in the project that is set as the Project for this mailbox rule.

Last modified: 04 May 2024