Introduction  

The incoming email account feature allows you to check an email account for unread emails and automatically create or process issues from the retrieved emails. With this feature you can:

• Create new issues from incoming emails
• Automatically add comments to existing issues from incoming emails
• Move issues through workflow steps via email

Setting it up  

Adding an account  

Before you can use this feature, you need to add an incoming email account.

 An "account" is the incoming email account in TBG, and contains more information than just the email account details.

You can add an incoming email account for any project by going to:

 Project -> Settings -> Email settings

From this page, click the "Add new account" button. A window will pop up, asking you for the account details. Any project can have as many incoming email accounts as you like.

Editing an account  

When adding a new or editing an existing incoming email account a window appears, asking for the following information:

• Account name - a name that will show in the list of incoming email accounts. Enter something descriptive. Cannot be empty.(example: Incoming Email)
• Server name - the incoming email server. Usually imap.<mailserver> or pop.<mailserver>. Check the email documentation for your email account.(example: smtp.server.com)
• Port number - the port number for the incoming email server. Check the email documentation for your email account.(example: 143)
• Email username / email password - the username / password for the incoming email server. Check the email documentation for your email account.(example: bugggenie@server.com)
• Account type - specifies the account type for the email server, POP3 or IMAP. Check the email documentation for your email account.
• Use secure connection - whether to use SSL when connecting or not. Check the email documentation for your email account.
• Issuetype - specifies the issue type new issues from this account will be created as. This lets you add "Support tickets" for support@yourdomain.com, and "Bug reports" for bugs@yourdomain.com, etc. One incoming email account can only convert to one specific issue type.

Click the "Add" or "Save" button in the bottom corner when you're done.

Checking for incoming email  

To check for incoming email, you will probably want to use the cli to set up a cron job - this way emails will be automatically processed when they arrive (or within a short time of arriving).

Checking via the cli  

To use the cli to check for emails, use the "check_incoming" cli mailing command:

 ./tbg_cli mailing:check_incoming

This command takes two (optional) parameters:

• status - Set to 'yes' to only show if there are mails waiting to be processed
• limit - Specify a limit to only process a certain number of emails (default 25)

Running the command will check for incoming emails on all accounts and all projects. You can set up a cron job to run this command and periodically check for new emails.

Checking via the web interface  

In the incoming email accounts list on the project's "Email settings" page, you can click the "Check now" button to check an incoming email account manually. The status below the incoming email account will show information for the last time the incoming email account was checked / processed, regardless of whether that was via the web interface or the cli.

Processing incoming email accounts  

Whenever the incoming email account is processed, TBG will look at the email subject and try to work out whether this is a new issue or an update for an existing issue. TBG will use the same detection rules as elsewhere in the system, so it should be able to pick up updates for existing issues with a high success rate. If it does not detect existing issues from the subject, it will create a new issue.

TBG will look at the senders email address and try to look up the user with that email address. This user will then be used as the user performing the action resulting from the email (e.g posting a new issue or updating an existing issue).

Creating new issues  

If the subject line does not match an existing issue in any way, TBG will create a new issue from the incoming email. TBG will use the subject of the email as the issue title and the email body as the issue description.

Updating existing issues  

If TBG detects that the email is an update to an existing issue, it will move on to processing the email. TBG will then look for a command line in the first line, and if it cannot find any, simply update the issue with a comment. Normal notification events will be triggered, so you can easily process and communicate through an issue without ever touching the web interface.

For all cases where TBG should update an existing issue, either hit "Reply" to the email notification or write an email with the issue number of the issue you want to update in the email subject.

Email commands  

You can use the available workflow actions for an issue as email commands to move the issue to the corresponding step in the workflow. To do this, enter the lowercase, unspaced name of the workflow transition as the first word in the first line of your reply. TBG will try and strip any quoted lines (including the line with the "User said:").

Example 1: Performing the "Confirm issue" transition on an issue
As the first line of your email, type "confirmissue", "confirm", "conf" (or anything short enough to still be distinctive). If you want to add a comment as well, start typing it on the next line.

 confirmissue

Example 2: Update the issue resolution
Type "resolution=<something>" where "<something>" is substituted with the lowercased, unspaced resolution you want to set. If you want to set it to "Can't reproduce", type "cantreproduce", "cantrep", "cant" (or something that is distinct enough to not match any other resolutions).

 resolution=cantreproduce

Example 3: Performing the "Resolve issue" transition on an issue, update the issue resolution, and add a comment
As the first line of your email, type "resolveissue", "resolve", "res" (or anything short enough to still be distinctive), followed by a comman, and then "resolution=<something>" where "<something>" is substituted with the lowercased, unspaced resolution you want to set. (If you want to set it to "Can't reproduce", type "cantreproduce", "cantrep", "cant" (or something that is distinct enough to not match any other resolutions).). If you want to add a comment as well, start typing it on the next line.

 resolve, resolution=cantreproduce, priority=low
 I can't reproduce this issue. Also, if I could, it wouldn't really be that important
 
 On Oct 2nd, automailer@domain.com wrote:
 > Hello username!
 > This email is to notify you [...]

Adding a comment  

If TBG doesn't detect any email commands in the incoming email when updating an existing issue, it will add a comment. The comment will be added without the quotation marks usually added by email programs.

Example: Reply with a comment to an issue notification email
As the first line of your email start typing your comment

 Can you please tell me what this is about?
 
 On Oct 2nd, automailer@domain.com wrote:
 > Hello username!
 > This email is to notify you [...]