How to set up Inbound Email Integration

Email Integration Plugin for Targetprocess connects to your inbox and retrieves email messages, binding them as comments to user stories (bugs, tasks, etc.) or creating Requests.

Create_request_schema

The Plugin uses POP3 or IMAP protocol for downloading emails. POP3 or IMAP incoming connections needs to be enabled in the internal settings of your mailbox.

IMAP protocol support requires Targetprocess v3.8.7+

IMAP

Targetprocess doesn't provide you with any default mailbox for incoming mails, so you are welcome to sign up with any third-party email service.

Both POP and IMAP integrations support only individual mailboxes. IMAP integration in Targetprocess cannot connect to the whole Exchange server and download messages from all inboxes in a bulk.

Troubleshooting connection issues with Gmail

Gmail service is supported. However sometimes Check Connection action rejects provided credentials. There are two possible causes.

A. Two-step verification is not enabled

Please try to enable two-step verification and register Targetprocess as an application in your Gmail account settings. How to register it. When Targetprocess is registered, take obtained 16-digit passcode and put it into Password field in plugin profile settings form instead of your regular email account password.

B. Captcha should be passed in web browser

When you receive the following error:

Cannot login: Wrong account name and/or password. The server responded: MBN00000003 NO [ALERT] Please log in via your web browser: https://support.google.com/mail/accounts/answer/78754 (Failure).; Connection settings: Protocol=imap, MailServer='imap.gmail.com', Port=993, Ssl=Yes

that means you need to open your web browser and navigate to https://accounts.google.com/b/0/DisplayUnlockCaptcha, then click 'Continue'.

Set up incoming emails

To set up the Plugin please go to Settings > Plugins and add Project Email Integration profile.

Connection settings

Pop_profile

Click Check Connection to make sure the settings are correct.

The Plugin checks for new messages every 5 minutes. This interval cannot be customized so far.

By default POP integration checks all incoming emails since the beginning of time. However, some smart email servers in POP settings allow to specify starting from what time moment messages will be available for download and whether any inner folders are visible for POP connections.

IMAP integration checks all emails in primary folder only. Messages from inner folders are not retrieved.

IMAP integration checks all incoming emails since the beginning of time. In order to let the plugin to download only messages starting from some specific moment and prevent creation of duplicated requests for older messages you have to move all old emails to a Archive folder in your IMAP inbox in advance.

Set up processing rules

At least one Rule should be added to let the Plugin process your incoming email and create Requests or Comments in Targetprocess.

Creating Comments only

It is good to add only one basic rule to let the Plugin accept your messages and add Comments to the related Targetprocess entities. Here is how you can set it up:

  • Choose or create the primary Project for your emails. This Project should always be active. Having the primary Project is a requirement for Email Integration plugin. In the meantime, the Plugin will attach Comments to other Projects as well, regardless if they are primary or not.
  • Go to the Details page for this Project and check if Helpdesk practice is listed below the Process name. Enable Helpdesk practice in the Process settings if it is missing there.
  • Check the Project ID number on the Project Details page. Say, it is #283.
  • Add a rule with the following syntax to the list of Plugin Profile rules:

    then attach to project 283

Creating Requests with Rules: create all Requests in the single Project

  • What would be a single rule to setup an email integration for all emails which should be created as requests?
  • Setup only one default rule:
    then attach to project 283 and create request in project 283

Here 283 is a numeric ID of the project that will serve as a container for all new requests.

This basic rule allows the Plugin accept your emails and either create new Request within selected Project if a message is not related to any existing entity or add Comment to the related Targetprocess entity.

  • Choose or create the primary Project for your emails. This Project should always be active. Having the primary Project is a requirement for Email Integration plugin.
  • Go to the Details page for this Project and check if Helpdesk practice is listed below the Process name. Enable Helpdesk practice in the Process settings if it is missing there.
  • Check the Project ID number on the Project Details page. Say, it is #283.
  • Add a rule with the following syntax to the list of Plugin Profile rules:

    then attach to project 283 and create request in project 283

Creating Requests with Rules: distribute Requests by multiple Projects using processing Rules

Rules have the following format:

when [conditions] then [actions]

Each rule should start with a new line. Rules specify the criteria that a message should match and the resulting action that is taken when the match is found. The rules are evaluated in sequential order, first to last. The first rule to match is the "winner" - after the first match the given message is no further evaluated against all subsequent rules.

For the final rule (i.e. applied by default when all the previous rules are not matched) the “conditions” part is not needed. The rule can start with "then" part.

Possible conditions
subject contains ‘keyword1, keyword2, …’Actions from “then” part will be performed if subject contains ANY of the listed keywords.

Keywords are case-insensitive.

Possible actions
create request in project 1234

create private request in project 1234

Private request will be created from email in this project #1234
create public request in project 1234Public request will be created from email in this project #1234
create request in project 1234 and attach request to team 567Private request will be created from email in this project #1234. Additionally, the request will be assigned to team #567.

The team should be assigned to the corresponding project in advance, otherwise the email processing error occurs.

create public request in project 1234 and attach request to team 567Public request will be created from email in this project #1234. Additionally, the request will be assigned to team #567.

The team should be assigned to the corresponding project in advance, otherwise the email processing error occurs.

 

Rejecting rule

It is not possible to specify a rule to reject a message so far. However, it is possible to create a dummy project for unintended messages and add an intercepting rule as a workaround.

Private and Public requests

Public and private requests are equally visible in Targetprocess tool. However, there is a difference in visibility in Help Desk portal. Public Requests are shown for all requesters that have access to some product. Private Requests are shown only to requesters specified in From: and CC: fields.

More details can be found here: https://www.targetprocess.com/guide/helpdesk-portal/helpdesk-faq/

Recipients in CC field

When request is created, the Plugin adds all users from CC: field as Requesters to the Request. This helps to keep all email participants notified about Requests.

Distribute incoming emails by client Companies

There is a "when" condition that helps to check to which company the sender user belongs to.

Possible conditions
company matched to project 1234actions from “then” part will be performed only if requester and project mentioned in “when” clause relate to the same company

Let’s say, we have 2 projects. Project1 with id=1 and Project2 with id=2. Project2 is assigned to Gmail company.

We can set the following rules in the profile:

when company matched to project 2 then create request in project 2
then create request in project 1

Rules are checked from top to bottom. Let’s see how these rules are applied to messages.

If an email is sent by the requester from Gmail company, that is from a @gmail.com address, this message will be attached to Project2 with ID 2 with the Request created in this Project (match by the 1st rule).

All the other messages matching neither of the first two rules will be moved to Project1, with requests created for Project 1.

Set up outgoing emails

To allow your users to communicate with Targetprocess using emails, please specify the address of your mailbox in two locations:

  1. On the Email Notifications settings page. The default address notifier@targetprocess.com is good for sending notifications, but the replies of your users to this address will never be processed, so you need to change it to your custom address for two-way communication.
  2. On the Project details page. This setting influences only communication with Requesters. Please check and modify Reply Email property if you would like to have different mailboxes for different Projects. Otherwise you can leave the field Reply Email blank - the default address from Email Notifications settings will be used.

Every outgoing email generated by Targetprocess has the line

--- Please do not remove this line! CompanyName Ticket#123 ---

in the bottom. It is important to keep the line when you post a reply back to Targetprocess. The Plugin searches for this line and adds a comment to the relevant Targetprocess entity when the line and the entity are found.

Troubleshooting

You should set up a unique profile for every mailbox. In the meantime it is non-recommended to set up two profiles connected to the same inbox because otherwise concurrent access issues can be observed and no requests and comments will be created.

IMAP email integration is downloading all emails from root Inbox folder. Other folders are not checked by plugin.

If your Inbox has many emails inside, then initial IMAP synchronization may take up to several hours to download all of them. Further regular checks should work fast.

  • Alistair Broomhead

    Is there any way of having replies to an automated email add comments to the Entity which triggered the email?

  • Alex

    Alistair hi! It is possible. Let me describe how it works. Quoting the article:

    Every outgoing email generated by Targetprocess has the line ‘— Please do not remove this line! CompanyName Ticket#123 —‘ in the bottom. It is important to keep the line when you post a reply back to Targetprocess. The Plugin searches for this line and adds a comment to the relevant Targetprocess entity when the line and the entity are found.

    Does this answer your question?

  • Alistair Broomhead

    Ah I had not fully read that section, it seems, the line ‘— Please do not remove this line! CompanyName Ticket#123 —‘ only appears in emails about requests, it seems like by editing the email template you can have it appear on other items, but the most useful place would be for replying to comments, where it comes out as ‘— Please do not remove this line! CompanyName Ticket#${entity.ID} —‘

  • Alex

    Exactly, Alistair!

  • Alistair Broomhead

    So how to get the entity id of the entity on which a comment has been made to show in the email template?

  • Kate

    By default Comment Created template already contains the required line. I have made the screen shot to clarify this

  • IcerPro

    Is it possible to automatically set a custom field to a request based on the subject (i.e. if subject contains ‘telephone’ then add ‘request type’ as ‘HelpDesk’) (where ‘request type’ is a custom field)

  • Alex

    It it not possible so far. If you require this feature, please request it, posting an Idea for upvotes to our public Backlog at http://tp3.uservoice.com/forum

  • IcerPro

    Hey Alex, I’ve added the request here.
    https://tp3.uservoice.com/foru

  • Roman Roiss

    Thank you guys for this great feature!
    However, i still have a problem on understanding the rules.
    I don’t understand what should happen when the message is attached to a project without creating a request.

    e.g.
    when subject contains ‘Test’ then attach to project 1

    what happens with the message ? where can i see it?

  • Julia Khmylova

    Hi Roman,

    Messages are available only in TP2 UI as for now.

    In order to see it in TP3 you’ll need to do the following:
    1. Go to Settings -> Mashups
    2. Install ‘TP2 pages’ mashups
    3. Add one more link ‘Messages’: ‘/Messages.aspx’,

    4. Save mashups, refresh the page

    As a result you’ll get a new menu item – TP2 – at the top, with a link to all your messages.

    Hope this helps,
    Julia.

  • Roman Roiss

    Hi Julia,
    Thank you yery much.
    Is it planned to implement messages in TP3 as well?
    br, Roman

  • Julia Khmylova

    We don’t have it planned yet, but you can raise its priority by voting for the corresponding idea: https://tp3.uservoice.com/foru

  • Scot Duffield

    Can I request that additional conditions be available? I’d like to be able to direct actions based on the domain of the email as well as the specific email address that the request originates from.

  • Alex

    Scot,
    Using ‘company’ keyword in Rule, you can define @domains in your system and forward requests into required channel project in dependency with origin domain. One domain – i.e. one Company per Project is supported. Is it acceptable? Do you require any guidance how to set up it? Or is it not enough for your needs and some additional actions should be made? Please let us know.

  • Albert Dieleman

    How do you modify an existing email integration add-on? I created one, but now want to edit the settings. In addition, how do I delete them?

  • Anna Ko

    Hi Albert,

    To modify your email integration please, open Settings – Plugins and click onto the profile name. You will be navigated to plugin profile details page, where you can modify any field, but the profile name. When done, just click ‘Save’ button and go back to plugins, or close the popup.

    To remove the profile completely, click at the red trash icon next to its name: http://prntscr.com/7fsvyz
    it will appear once you hover your mouse in the plugin name area.

    Regards,
    Anna K.

  • Albert Dieleman

    Thanks for speedy response. I cannot see the profiles, nor the trash button. I’ve attached a screen shot to show you.

  • Sebastian Oschatz

    can i check incoming mails to have something like “case xxx” in the subject and then have them appended to the item with the id xxx?

  • Kate

    @sebastian_oschatz:disqus the only way for Targetprocess to know what existing entity to attach the mail to is the line in the bottom of the message body, that says:

    ‘— Please do not remove this line! CompanyName Ticket#123 —‘

    It is not possible to refer the id in the Subject

  • Sebastian Oschatz

    the idea here is using TP as an email archive, so that users can quickly append incoming email (including attachments) to certain items, rather than copy paste.

    so you are saying that any email containing
    ‘— Please do not remove this line! CompanyName Ticket#123 —‘ will get automatically be appended to the item 123?

    so is it possible to change that string?

  • Kate

    @sebastian_oschatz:disqus
    Yes this string allows to attach e-mail to any entity in Targetprocess.
    What you are trying to implement is described above in section “Creating comments only”.
    If you change it – Targetprocess will not parse the e-mail and will not attach the comment.

  • Cynthia

    We’re just implementing this feature. Would be GREAT if the CC: in the email could assign a specific person to the request. We are using this to manage a company, not manage software development so we are using the tool quite differently.

  • Alex

    Cynthia what do you mean by ? How should it work “CC: in the email could assign a specific person to the request”? Now the plugin takes all CC: users and adds them as requesters. Is it good or not? Should we provide some additional control over this rule?
    We also have a UserVoice discussion related to this topic here http://tp3.uservoice.com/forum… – please don’t hesitate to upvote it and share your opinion there!

  • Cynthia

    Hi Alex:
    What I would like to do is have the Requester be the sender of the email and I would like the person in CC or TO be the person who the request is assigned to in the specific project. So if I send an email:
    To: Targetprocess@companyname.com
    cc: name@companyname.com
    Subject: Project ID
    I would like this attached to Project ID and I would like it assigned to name@companyname.com with the requester being the sender of the email.
    Obviously we are using it in a different way than it was designed (not for a helpdesk or bug reporting).

  • Alex

    Thanks! It makes sense and indeed having such rules may make this email integration module much more helpful. When our UX team will think about improvements of existing email integration system, we’ll consider the suggested improvements.

  • Cynthia

    And better yet! If I could add something like Tag:Urgent and the request could be colour coded, then this would be really nice. The email feature is one of the most important productivity improvements for us.

  • Andrey Metelsky

    Thanks for your feedback!

    As a workaround you can use webhooks to automatically add corresponding tags depending on some conditions: http://screencast.com/t/8MEet3… here it adds tag “urgent” to request that has such word in it`s Name.
    Please find out more here: https://www.targetprocess.com/

    Another possible option is to use Zapier integration. You can use it in addition to Email integration or instead of it. Zapier also allow you to automatically add some tags to new added requests, but will also created them in Targetprocess, so there are can be some duplicates. Please read more about Zapier in our guide: https://www.targetprocess.com/

  • Dennis Swennen

    Can I use this setup also to add a shared mailbox?

    I would like to login with my work e-mail address, yet the purpose is that TargetProcess checks the ‘support@…’ shared mailbox, that will receive the requests in the inbox.

  • Sergey Gnedin

    @denniswennen:disqus absolutely! We use support@targetprocess.com for example and keep our work emails to log in. You still need to specify that email password in plugin settings, though.

  • Ironbelly Studios

    This may seem obvious but what is the difference between a private and public request? Mainly who can see the private request? Only the project manager or project owner?

  • Julia Pastushenko

    Public and private requests are equally visible in Targetprocess.
    However, there is a difference in visibility in Help Desk: https://www.targetprocess.com/

    So if you’re not using Help Desk portal there is no difference between public and private requests in Targetprocess.

    Hope this helps,
    Julia.

  • Ironbelly Studios

    That makes sense and is useful to know as we will be using the helpdesk portal in the future

  • CarlosTech

    when you reply to a comment that you’ve been tagged to, is there anyway to set the incoming email as a “reply” to said comment.

    i notice that when you reply it simply creates a new comment in the ticket but doesn’t notify the person being replied to… i’m seeing if i can streamline this for certain users who find it easier to simply ping off a response via email as opposed to logging on to TP and replying.

  • Alex

    Carlos, it is not possible unfortunately. We have ideas related to this improvement posted to our public backlog for future changes and I’ve added votes on your behalf to them:
    https://tp3.uservoice.com/foru
    https://tp3.uservoice.com/foru

  • CarlosTech

    hi TP, is there a way to ask TP to ignore Out Of Office emails when a users OOO replies back to the sending email address. i’ve noticed that it creates new tickets every time.

  • Bogdan Skaskiv

    Hello Carlos,
    There are two possible ways how to achieve this:
    1. Filter your message using rule in Targetprocess,attach message to the project but don’t create request based on it ( when subject contains ‘Out of Office’ then attach to project 1)
    2. You can also filter your message directly in your mailbox which will be easier as it can parse not only subject but other parts of email and automatically delete it or move to some folder. In this case it won’t be processed in Targetprocess
    Best regards,
    Bogdan

  • Karen Meaney

    TIP, if you want emails that were not originally from tp to append as a comment (e.g. vendor update) set a signature in outlook with — Please do not remove this line! TCMA Ticket#00000 — then if you want to forward and create a comment you only need to add the ID number.

  • Maxine

    I just set up email Integration and it is working so far – my colleague sent an email from her work account and it was processed into a request.I commented on the request and she got an email as well. BUT my Sender email address is a different one (I think the one that iI put in for email notifications?), so when she answers to my comment, this email doesn’t go to my inbound email box.
    I understand that I could put my inbound address as sender address as well. But as I can have multiple inbound addresses I don’t understand how it is supposed to work with only one sender address.
    Thank you in advance!

  • Kate

    @disqus_GiEW00cl90:disqus You are welcome to set up Sender e-mail under Settings -> Email Notifications. You can as well set Reply e-mail per Project. This can be done under Project details View:
    https://uploads.disquscdn.com/images/a156377b5bf624a5b93c935dab2c242e3ec2a62c3fbb0f6ca68c5f92bcf74fb4.png

  • Maxine

    Hi Kate,
    thank you for your response. I am not able to type something into the box next to “Reply Email”. Are there any Settings I need to do first?

  • http://targetprocess.com Bogdan Skaskiv

    Hello Maxine,
    There are no settings that would prevent you from typing text in there. Please try to clean your browser cache or open Targetprocess in another browser. This should help.
    Best regards,
    Bogdan

  • Maxine

    Good morning 🙂
    I tried another browser (Google Chrome) and it worked. IE didn’t work.
    Thank you guys!

Still have a question?

We're here to help! Just contact our friendly support team

Find out more about our APIs, Plugins, Mashups and custom extensions. Join our community of passionate users and even discuss directly with our developers.