Please log in to subscribe to updates for this article
Last updated at Mon 03 Mar 13:52, by kanto501
Table of contents
Introduction ⇑ topThe 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 ⇑ top
Adding an account ⇑ topBefore 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 settingsFrom 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 ⇑ topWhen 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: firstname.lastname@example.org)
- 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 email@example.com, and "Bug reports" for firstname.lastname@example.org, 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 ⇑ topTo 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 ⇑ topTo use the cli to check for emails, use the "check_incoming" cli mailing command:
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)
Checking via the web interface ⇑ topIn 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 ⇑ topWhenever 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 ⇑ topIf 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 ⇑ topIf 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 ⇑ topYou 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.
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).
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, email@example.com wrote: > Hello username! > This email is to notify you [...]
Adding a comment ⇑ topIf 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, firstname.lastname@example.org wrote: > Hello username! > This email is to notify you [...]