You are viewing documentation for the older version of YouTrack!

Skip to end of metadata
Go to start of metadata

Mailbox Integration

Mailbox Integration allows creating issues automatically from e-mails sent to a particular email address. That is, when a user sends a message to a specific e-mail address, then YouTrack will fetch this message and automatically creates an issue based on it. An issue is created with the following parameters:

  • IssueID automatically generated in the specified project
  • Issue summary generated from the original message's subject
  • Issue description generated from the original message's body
  • Issue reporter set according to the specified rule: either an author of the original message or a pre-defined user.

If YouTrack finds that new received email relates to a previously created issue, then the body of this message is added to the issue as a comment. To determine that the message relates to an existing issue, the following strategies are used:

  1. Standard MIME threading by 'message-id'/'in-reply-to'.
  2. Reference to the issue id in the subject.
  3. Threading by subject, excluding 'Re:', 'Fwd:' and ignoring content within square brackets (the same strategy that GMail uses for threading).

Mailbox Integration is bundled in YouTrack and you can configure integration parameters in Administration > Mailbox Integration section of YouTrack's web interface:

To enable MailBox integration, you need to perform three steps:

  1. Configure connection to a mailbox
  2. Configure rules to apply to incoming emails
  3. Configure schedule for fetching emails

Configuring Connection to a Mailbox

  1. In Administration > Mailbox Integration section, click Add mailbox link:
  2. In the Add new mailbox dialog window, configure the following parameters:
    • Protocol — the protocol used in the specified mailbox
    • Host — Mail server URL. For example,
    • Port — Mail server port. By default, the standard port number is set automatically, according to selected Protocol value.
    • Login — User name to authorize access to the mail server
    • Password — password to access the mailbox
    • Connection timeout — set the timeout for the connection to the mailbox. By default the timeout is 30 seconds.
    • Socket timeout — set the maximum amount of time to wait for a response from the mailbox before disconnecting the socket. By default, the value is set to 'infinity'.
  3. When the above parameters are set, click the Test Connection button, to check whether the specified mailbox configuration is correct. If test connection is successful, save the specified configuration; if test connection cannot be established, correct your settings and test the connection again.
  4. Click Save to create the new mailbox configuration, click Cancel to exit the dialog whithout saving parameters.

When a mailbox connection is configured, you should create a rule describing which messages should be processed and how.

Configuring Rules for Processed Emails

To configure rules for processing incoming emails and creating issue from them:

  1. In the Administration > Mailbox Integration tab click define rule link.
  2. In the Main tab of appeared dialog window, specify the following mandatory settings:
    • Project — specify a project in YouTrack, where the new issues generated from emails will be created.
    • Mailbox — select a mailbox, from which YouTrack should fetch emails.
    • If needed, select Maintainer of the rule. Maintainer receives notifications when a command is unsuccessful or reporter could not be resolved. By default, a user who created the rule is set as Maintainer.
      All other parameters are optional.
  3. In the Filter tab you can specify which emails should be fetched:
    • Folder — specify an incoming mail folder. Default value is a standard incoming mail folder for the specified mailbox, e.g. Inbox. To fetch emails from the default folder, leave the field empty.
    • 'To' address — specify an email address to filter incoming emails by it so only emails sent to to this address will be processed by YouTrack. If an email address is specified here, then all automatically created notifications will be sent to users from this address. If the field left empty, then all e-mail from the specified folder will be processed.
    • Ignore auto replies — if enabled, all auto-replies will be ignored and not processed by YouTrack.
  4. In the Reporter tab, select who will be set as a reporter of a created issue.
    • Set email sender as reporter. Default option. YouTrack resolve e-mail address of an email's author, and tries to find a user account with the same address. If such account found, then the user will be set as the reporter for the issue created from the email.
      If no user with sender's email address found in YouTrack, then:
      • Create new account for sender. If this option is selected, then for a sender a new account will be created. Account is created based on sender's email address. New credentials for accessing the YouTrack instance will be send to the author of the original email in the notification message about creating issue from the email.
      • Set <select user> as reporter. — Select an existing user, which will be set as an issue reporter, if no user account with sender's email address is found.
    • Always set <select user> as a reporter. If you've enabled this option then Youtrack will always skip searching for an existing user account and set the user specified here as a reporter for any new issue created from an email.
  5. In the last, Postprocessing tab, you can specify what should be done when an issue is created:
    • Apply command — specify a command to apply automatically to a created issue. For example:
      In a command to applied to issues created from an email, we support a ${from} variable in commands, which will be set to the e-mail's 'From' e-mail address. The example command provided above means that any new issue created from e-mails (matching specified rule) will be assigned to user and a custom field 'fromMail' will be set to a sender's email address (email address in the 'From' field of the message).
    • Delete fetched email — if enabled, fetched email message will be deleted from the mailbox after an issue has been created.
  6. When done with all the needed settings, click Save to create new rule, or click Cancel to close the dialog without saving.

At the bottom of the dialog window you will see a note in the following format: "Maintainer of this rule is <user name>. He receives notifications, if rule can't apply command or resolve reporter."
A user who updates a rule, automatically becomes the rule's maintainer and will receive notifications when a command is unsuccessful or reporter couldn't be resolved.

Configuring Schedule for Fetching Emails

You can specify a schedule for fetching emails from the specified mailboxes using a cron expression. Please note that schedule is not created for each specified mailbox individually. The same schedule will be applied for all mailboxes.

To specify an interval for mail fetching, click the Common Settings link, and in the appeared dialog type a cron expression. For example, to fetch emails from the specified mailboxes each 15 minutes, every day, use the following expression:

For details about cron expressions format, please refer to the cron trigger tutorial.