Email Connector
Introduction
The Commit Email Connector module allows you to process incoming emails and perform appropriate actions (like creating new Tickets). It also allows you to parse and analyze XML formatted emails that contain new Tickets, Accounts, Assets or other Commit record information.
The Commit Email Connector module automatically generates new Tickets from emails sent by clients to a defined public email address. It also provides a full API to Commit using XML formatted email messages.
This instructional video covers the basic Email Connector Installation flow, to review it please click here.
Email Threading
The Email Connector manages email threads for you. If a customer replies to your support email in regards to a specific ticket, or if you, as a technician, reply to the customer, the correspondence will be automatically filed under the ticket in the system and distributed automatically to the recipients defined for the Ticket.
There are two email threading scenarios:
- A customer replies to Support regarding an email sent from the system, which contains a ticket number in the email subject. In this case, the system files the email under the ticket and distributes it to the Ticket Recipients.
- An employee replies on a customer email, which contains the ticket number in the email subject. The employee needs to send the email to the support email address, and Commit Email Connector will automatically file the email in the system and distribute it to the Ticket Recipients. When a technician Cc or Bcc's the Email Connector, the email will be filed in the ticket, and will not be distributed to Ticket Recipients.
Note that the email threading management will apply only when the sender email address is defined as one of employee's emails (Email1 or Email2), and the employee is marked as an Active employee in CommitCRM. See more details on matching the email to an account in Matching by Email or Domain Name. In both cases, the Email Connector receives the email, finds the ticket in the subject, finds the ticket in the database, and then files the email as a document under the ticket history.
For detailed explanation about how email threads are managed by Commit Email Connector, see the Ticket Management user guide under Email Distribution via Commit Email Connector.
Matching by Email or Domain Name
Commit connects an incoming support email to specific accounts based on the full email address of the sender, or by the domain name (if defined for the account).
If one of your clients has many possible email addresses, you should either add each of the email addresses as the email in the secondary contact (in the Account Contacts tab), or define the client's domain name in one of the Account's email addresses or secondary contacts.
To define a domain name for an account:
Set the domain name (e.g. "commitcrm.com") as the email address in one of the following places:
- Account's Email field (in the General tab)
- Account's Email 2 field (in the Address tab)
- Add a secondary contact, and set the domain in the contact's email field
Notes:
- Account detection will first try finding the full email address.
- Only if this email address does not exist in the database, the system will search by the domain name.
- Duplicate domain names will create an error when processing the incoming email. Note that the system does not prevent entering duplicate domain names.
Commit Email Connector Setup
The Commit Email Connector is a plug-in for the Commit Server. Setting up the Commit Email Connector module includes using general settings used by the Commit Server, and specific settings for the Email Connector plug-in.
To run the configuration application:
- Log into the Server with a Windows Administrator user. Note that the setup program must run from the same server as the one where the Commit installation sits and from where you plan to run the Email Connector.
- Run <Installation_DIR>\Server\ServerConfig.exe
The following window will open:
The server configuration window consists of the following three tabs:
- Outgoing Mail Server Settings - here you can define the settings for all outgoing emails sent by the Commit Server.
- Email Connector Settings - here you can define all the settings for the Commit Email Connector.
- Email Alerts Settings - here you can define all the settings for the Commit Email Alerts (not in the scope of this document).
In order to run the Commit Email Connector, the following settings should be configured (in this order):
- Outgoing Email Setup - Define the setting for outgoing emails. These settings will be used by the Commit Server for all outgoing emails.
- Incoming Email Setup – Set up the mail server and incoming mailbox which manages incoming emails prior to being processed by the Commit Email Connector.
- Email Processing Setup - Define how incoming email is processed. Commit Email Connector reads each email and performs the actions as defined in these settings.
- Internal Support Team Email - Define settings for the Internal Support Team Email, which is used if the system cannot decide what to do with the Email, or if there are errors.
- Installing and Running Commit Email Connector Service - After setting up all of the above, you should actually install the Email Connector service and run it on your server.
Only once the setup is complete can you run the Commit Server and start using the Commit Email Connector plug-in.
To set up the Email Connector, start with the Outgoing Email Setup below.
Outgoing Email Settings
The Outgoing Email settings are used for any outgoing emails sent from Commit Server.
Note: The Outgoing Email settings should be set only once for the Commit Server, so if you already defined this for the Email Alerts Server, you can skip this step.
The Outgoing Email settings should be set in the Outgoing Mail Server tab.
To reduce errors and improve security, it is strongly recommended to use SMTP authentication, with a user name and password for SMTP access.
Parameters:
- SMTP Host - your Outgoing SMTP Mail Server
- Port - the Outgoing SMTP port
- My outgoing server (SMTP) requires authentication - if checked, must fill in the authentication details below:
- User Name - the User Name to be used for SMTP authentication
- Password - the password related to the specified User Name
Note: If you use SSL on your Email servers, please read this article in order to find out how to set up the Commit Email Connector with SSL.
Verification Tests (required!):
- Test SMTP Connection - click this option to verify that your account is working. If there is missing or incorrect information, such as your password, you will be prompted to supply or correct it.
- Send Test Email - Use this option to send an outgoing email using the settings you defined. After clicking it you need to specify the From email address and the To email address that will be used for sending the Test Email message.
After completing the Outgoing settings, move on to the next step > Setting up the Incoming Email Settings.
Incoming Email Settings
After setting up the Outgoing Email settings, you should now define the incoming mailbox settings.
Setting up the Incoming Email Settings includes four steps:
- Setting up the Email Connector Status
- Setting up the Public Email Address
- Setting up the Incoming Mail Server
- Setting up the Backup option (optional)
To set up the Incoming settings, go to the Email Connector tab:
In this window, fill in the settings as explained in the following sections:
Email Connector Status
The Commit Email Connector status can be one of the following:
ON (default) - Commit Email Connector is active and processes incoming emails.
OFF – Commit Email Connector is not active and does not process incoming emails (emails are left in the defined mailbox until you review them manually or turn the connector to ON again.
Note that in order for the status changes to take effect, you should restart Commit Server Service (see Running Commit Email Connector).
Public Email Address
The Public Email Address is the main support email address (e.g. support@yourdomain.com) to which customers can send support-related emails. Tickets are automatically created out of these emails, and this address is also used to process XML-formatted emails (API) sent by external systems, such as a form on your website. All Emails sent to this email address will be analyzed and processed by the Commit Email Connector.
Note: This email address should ONLY be used as the incoming email for the Email Connector. You should define a different address for your internal email which will be used for unrecognized emails, error handling and direct email threads with your customers (see Internal Support Team Email).
Public Incoming Mail Server
In this section you will define the pop server settings of the incoming email server:
Server Information
POP3 Host - your Incoming Mail Server (POP3)
POP3 Port - the Incoming Mail Server port (POP3)
Logon Information
User Name - this is the incoming public support email account used for the Incoming email address described above.
Password - the password for this email account.
Note: To use Commit Server service with Microsoft Exchange servers, ensure that POP3 is enabled for the relevant account in the Exchange server.
Note regarding SSL: If you use SSL on your Email servers, please read this article in order to find out how to set up the Commit Email Connector with SSL.
Misc.
Test - click Test to verify that your account is working. If there is missing or incorrect information, such as your password, you will be prompted to supply or correct it.
Advanced - set up timeouts for the connection and polling interval (in most cases you should use the default values).
After filling in the information on this screen, we recommend you test your account by clicking the Test button (requires you to run the setup program from the Server).
Backup Settings (optional)
Once an incoming email has been processed by the system, it is removed from the email server (i.e. deleted from the mailbox). For backup and tracking purposes, you can automatically forward all emails to a dedicated email account for storing.
To set up the backup email account:
Backup ALL Incoming Emails – select this option to activate the backup.
Send ALL to this Email Address – Enter the Backup Email Address which will be the backup mailbox. Note that this must be a different email address than the Email Connector Incoming Email Address to avoid deadlocks where the backup email is being sent to the Incoming Email Address over and over again
After completing these settings, move on to the next step > Setting up Email Processing Settings email-to-ticket settings).
Email to Ticket Settings
After setting up the Incoming Email Settings, you should now define the settings which will be used when converting incoming emails into Tickets in the system.
When receiving a new incoming email, the system recognizes the email sender's address or domain from the Commit Accounts database; it automatically opens a Ticket and copies the email content into the Ticket description (the text/plain part). The Ticket will be automatically linked to the Account that matches the email address.
Matching by Email or Domain
Matching the incoming email to a Commit Account is performed based on the full email address of the Account, or by the domain name (if defined for the account). This is because clients may be using generic email addresses (such as Yahoo®, Gmail®, etc.) and the system cannot rely on any domain name. If one of your clients has many possible email addresses, you should either add each of them as a secondary contact (in the Account Contacts tab), or define the client's domain name in one of the Account's email addresses or secondary contacts. See more details in Matching by Domain Name.
Email-to-Ticket Settings
While creating a new ticket, the system can:
- Store the original email and link it to the ticket
- (Optional) Send an automatic response to the email sender or forward the response to an internal email for backup purposes
Setting up the Email Processing includes:
- Setting up Automatic Response options to the customer, and defining a BCC address for responses.
- Setting up the Store Folders in which the original email will be saved
Setting up the required parameters for this is done in the following window:
Auto-Response Settings
Setting up the Response Parameters includes:
To send automatic responses to clients who have sent emails, set the following parameters:
- Send Response – Select this option in order to send automatic email responses and notify your customers who sent emails that became new Tickets.
- Edit response Text – Click this button to edit the text of the response email.
- Attach the original email to each response – Select this option to attach the original email sent by the client to the response email.
- BCC email response to (optional) - You can select this option to automatically BCC your own support team to be notified, via email, on all responses to customers emails that became new Tickets (DO NOT set the BCC email address to be the same as the Email Connector Incoming Email Address, which is being processed by the Email Connector).
Store-Folder Settings
Setting up Store Folder includes:
This is the folder on the server's local disk in which emails that became Tickets are stored so that they can be attached to their Ticket.
Ideally, all emails that create a ticket for a specific account, will be stored in the account's Documents folder (each account's has a default folder defined for storing documents; click the account's Details tab to see the Docs Dir field). This way you will have all of the files that are relevant for a specific account, located in the same physical place on your server. All email files are saved as .eml files.
In order for the Email Connector service to be able to save the emails in each account's folder, you must configure the folder location so that the service will have the correct access to it.
This requires setting up the main Documents folder (under which you save all account's files) in the Allow Folders list. Setting up the folder teaches the Email Connector service how to map between the path appearing in the application as the account's Documents folder, and the way it can be accessed by the service itself.
Setting up the Allow Folders list includes setting up two paths:
- The path recognized by the Commit Client application, so it will be able to identify the correct path as it appears in the account's documents folder
- The path recognized by the server as a local folder on the computer
After setting up the Allow Folders, you should also set up the Default Filing Folder, which will be used as a backup if the service cannot access the Account's documents for some reason (e.g. due to permissions issues). The Default Filing Folder will be used for such cases, to make sure the service can store the email.
Go to Default Filing Folder, and define both paths, as the server recognizes it and as the client recognizes it.
After completing these settings, move on to the next step > Setting up Internal Support Team Email (for forwarding emails).
Note that the Email Connector also provides more advanced processing options, such as using the Email Connector as an API (via XMl transactions), or using Automated Emails. You can read more about the advanced Email Connector options in the Advanced Email Processing section.
Notifying Customers and Technicians on new Tickets
Email Connector allows you to notify your customers that the emails they sent became new Tickets.
You can set Email Connector to send an automatic response back to the customer, notifying him or her that a Ticket was opened out of his /her email. When you configure this in the ServerConfig, you can also define a BCC address for keeping track of these emails. In the BCC address you can enter your Internal Support email to receive each notification as an email.
All automatic responses are automatically forwarded back to the Email Connector, and filed under the Ticket as part of the ticket history.
Internal Support Team Email
After setting up the Outgoing Email Settings and the Email to Ticket Settings, you should now define the Internal Support Team Emails (for forwarding purposes).
The Internal Support Email address is your main activity support mailbox which should be constantly reviewed by your support team. This mailbox will be used by the system in cases where the system cannot decide what to do with the email. The Email Connector will automatically forward these messages to this email address which should be reviewed by a "human" support team to identify emails which need to be handled manually.
Note: If the Ticket was not found in the Commit database, the email will be forwarded to the Internal Support Team email, with an error indicating that the Ticket cannot found.
The Internal Support Email Address is set in the following window:
Email Address - This is an internal mailbox which will be used by your support team (e.g. support-internal@yourdomain.com). This mailbox should be manually reviewed on a regular basis to make sure there are no customer issues awaiting response which were filtered out for one of the reasons listed above, and to make sure that other email threads also receive the appropriate response.
General Settings
You can select to have unrecognized/error emails forwarded either as attachments or as is:
Send original as an Attachment – Attach the original email to a new message.
Send original As-Is – Send the original email in its original form (i.e. with the same "From" address) directly to the Internal Support Team Email Address. This option is usually more convenient, though it may not be supported by your mail server as it demands support relaying.
The Internal Support Email address is used for the following purposes:
- Unrecognized emails – Unrecognized emails from new customers not yet in the Commit database will be forwarded to this address (and no Ticket will be created).
- Error Handling - Emails which could not be processed due to errors during the process (such as the wrong format in XML formatted emails) will be forwarded to this mailbox.
Make sure not to use the same email address for the Internal Support Email as you do for the "Public Email Address." Also, make sure that emails sent to the Public Email address and the Internal Support Email address do not end up in the same physical mailbox (i.e. that they are not synonyms/aliases for the same mailbox).
After setting up all of the above, you are now done with the setup and can move on to actually running the service and activating the Email Connector. See more details in Running Commit Email Connector.
Running Commit Email Connector
After you finish setting up all of the required settings (see Commit Email Connector Setup Overview), you can move on to the next step and install the Email Connector service.
The Commit Email Connector runs as a plug-in for the Commit Server. The Commit Server runs as a Windows Service on your server.
Before you install the Commit Email Connector
- Make sure to complete the Setup steps prior to installing the Windows Service.
- Make sure to allow the Commit Email Server Service in your DEP settings.
Install:
This part of the installation should be performed on the server itself.
When logged in to the server with a Window's Administrator account, open a command prompt window and enter the following command:
<Installation_DIR>\Server\CommitServer.exe -install
Note: The <Insallation_Dir> must refer to a LOCAL server path (e.g. c:\ or D:\Software, etc.) and NOT to a shared network name/path.
A service called CommitServer should now be displayed in the system services management window (Control Panel > Administration Tools > Services).
Start the Service:
Using the Window's Services Management window, start the service (right-click > Start).
Make sure that the service is running and that it is set to start automatically (Startup type > Automatic) each time the server is restarted.
Troubleshooting:
In any case of problems, see the Troubleshooting section below.
Uninstall: To Uninstall Commit Server stop the CommitServer service and then type the following command in a command prompt window on the server:
<Installation_DIR>\Server\CommitServer.exe -uninstall
Advanced Email Processing
API by Email
The Email Connector provides advanced processing options, such as using the Email Connector as an API by sending in XML transactions by email.
Setting up the API by Email section is optional and is required only when working with external system which send XML formatted emails to the Email Connector.
See more details in API by Email
Automated Emails
The Email Connector provides advanced processing options, such as using formatted Automated Emails.
Setting up the Automated Emails is optional and is required only when working with external systems (such as external MSP system) which send formatted email alerts to the Email Connector.
The Automated Email feature in CommitCRM processes incoming emails that have been sent to the Email Address defined for the Email Connector. The emails processed are from automated sources, such as an MSP alerting application, and the Automated Email feature analyzes the email's header in order to create the relevant Tickets in CommitCRM.
This feature allows you to define a set of rules which will be activated one after the other to help the system detect pre-defined email formats, and create Tickets for them. As opposed to the "New Ticket From Email" feature, automated emails do not necessarily originate from a customer's email address, so it is difficult for the system to determine the customer for whom a new Ticket should be opened.
The Automated Email feature allows you to define a set of rules that will help the system detect automated incoming emails which contain information about specific customers, and create Tickets for them.
See more details in Automated Emails
Troubleshooting
For troubleshooting, see Commit Email Connector Troubleshooting