Sugar® can be configured to monitor group email accounts and then perform a corresponding action. One of the most useful applications for this behavior is the email-to-case functionality. This article explains how to configure Sugar to automatically create a new case record when it receives an email message.
Emails sent to a monitored group mail account will be automatically converted into a Sugar case record related to the account that corresponds to the sender’s email address. The new case will be assigned to a user on the preferred team in a round-robin fashion, or Sugar can assign the case to the user with the smallest caseload.
Beginning with version 9.1.0, each user’s license type (e.g. Sugar Serve) determines what functionality is available as described in the User Management documentation. Please note that the Cases module is not available for Sugar Sell users.
There are several items that must be properly configured before setting up the email-to-case functionality:
- You must be an administrator user.
- A team must be set up whose members are the users you wish to be assigned to the created cases.
- Sugar’s outbound email must be configured via Admin > Email Settings.
- Schedulers, specifically the Inbound Email Scheduler, must be running.
For more information on these configurations, please refer to the User Management, Team Management, Email, and Schedulers documentation.
Optionally, you may also want to create a template for automated email responses. When a person sends an email message to the monitored email account, Sugar can send a reply email notifying the sender that a case has been created as a result of their message. If you wish to use the auto-reply feature, you must first create the email template via Emails > Create Email Template. For more information on creating email templates in Sugar, refer to the Emails documentation.
- Configure the inbound email account that Sugar will monitor by navigating to Admin > Inbound Email. From the actions menu, choose “New Group Mail Account”.
- Configure the fields in the Mail Account Information section. All required fields are marked with a red asterisk in Sugar and must be completed prior to saving.
Note: If your mail account is using Gmail, click “Prefill Gmail™ Defaults” to populate many fields with default values that are specific to Gmail.
|Name||Enter a descriptive name for this group email account in the Name field.|
|Status||Set “Status” to “Inactive” until you have completely and accurately configured the group email account and you are ready to start creating cases from emails.|
|Mail Server Address||Enter the monitored email account’s incoming email server web address (this is often in the format “mail.example.com”).|
|User Name||Enter the username for the email account that will be receiving email messages.|
|Password||Enter the password for the email account that will be receiving email messages.|
|Mail Server Port||Enter the communication port number used for connecting to the email server. This option will pre-populate with the most common port number as determined by your protocol choice. If you are not sure what port number to use, then leave it set to this default port number.|
|Mail Server Protocol||Select from the two different methods used to access email, either IMAP or POP3. This option will determine how you will be able to interact with your email account once a message has been received.IMAP : IMAP is the preferred protocol for the email-to-case functionality. It allows you to receive emails on multiple devices such as a work laptop, a home computer, and/or a mobile device. Because IMAP stores email messages directly on the email server, the messages are accessible from any email-enabled device, even after you have retrieved the messages elsewhere. Because Sugar will be receiving emails for this account, it is advantageous to maintain the ability to browse emails in an alternative email client when needed.POP3 : Although Sugar supports the POP3 protocol, it is not the recommended method for the email-to-case functionality. Once a POP3 message is retrieved, it cannot be accessed from any other device. This means that if Sugar successfully retrieves an inbound email message, it will not be possible to view the message on any other device. Alternatively, if a secondary device retrieves the message before Sugar’s scheduler does, then Sugar will not find the new message, thereby failing to create a case record.For IMAP configuration only, you must select the existing mailbox folder that you wish to monitor from the Monitored Folders field, and specify which folders your email account uses for the Trash and Sent folders.For both IMAP and POP3, you must decide whether to select the Use SSL checkbox. If your email server supports secure socket connections, enabling this option will force SSL connections when importing email. If you are not sure whether your server supports SSL, then leave this field blank.|
- Configure the fields for the Email Handling Options section. All required fields are marked with a red asterisk in Sugar and must be completed prior to saving.
|Assign To Teams||Select the teams that should have access to this email account in Sugar.|
|From Name||For sent emails that may be triggered by an action, specify the display name that will appear in the “From” address section in the recipient’s email client, such as “Customer Support”.|
|From Address||Depending on your email service provider, you may be able to specify a unique email address to appear in the “From” address section of sent emails. Some email service providers do impose restrictions on this practice, in which case the email address defined in your system’s outgoing email server will be used.|
|Reply-to Name||Enter the display name that you would like to appear for any replies to the auto-reply template.|
|Reply-to Address||Enter the email address that you would like to use to receive any replies to the auto-reply template. This should be a different email address than the From Address to prevent creating duplicate cases.|
|Import Emails Automatically||Select this option if you would like to automatically archive the received email to Sugar.Note: Even with this enabled, schedulers are still required to run routinely to import emails and create cases.|
|Create Case from Email||You must select this option to automatically create case records in Sugar from incoming emails. Selecting this option will reveal two additional fields.Distribution Method : Decide how Sugar should assign case records. The Round-Robin option will distribute cases evenly among all users within the team specified in “Assigned To Team”. The Least-Busy option will distribute cases to the user with the smallest case load within the team specified in the “Assigned To Team”.New Case Auto-Reply Template : Select the auto-reply email template that you created in step 1. By choosing the auto-reply template here, Sugar will insert special Case Macro markup in the subject line. This response is only sent when the first email is received from the recipient. Sugar identifies future emails by the Case Macro, imports them, and relates the email messages to the corresponding case record.|
|Allow users to send emails using the “From” Name and Address as the reply to address||For Sugar 7.9.x and lower, when this option is selected, the “From” name and email address associated with this group email account will appear as an option for the From field when composing emails in Sugar for users on teams that have access to the group email account.Note: This functionality was deprecated as of Sugar 7.10.x and will have no effect on versions 7.10 through 8.x. As of Sugar 9.0.0, this option has been removed as you can create shared email accounts directly via Emails > Email Settings which allows groups of users belonging to the assigned team(s) to send outbound email messages using the same email account (e.g. firstname.lastname@example.org).|
|Auto-Reply Template||In addition to the “New Case Auto-Reply Template” explained above, you may also choose to send an automatic reply email letting the sender know that their email has been received. This field does not recognize the template as a new case reply and therefore does not insert case macro markup in the subject line. Be aware that this second auto-reply may cause confusion or be a nuisance to the sender if it is too similar to the new case responder.|
|No Auto-Reply to this Domain||If you would like to exclude a certain domain from receiving an automatic email response, enter that domain name here. It is common to specify your organization’s domain to prevent auto-replies from being sent to your organization’s members.|
|Number of Auto-Responses||Enter the maximum number of times you want Sugar to send an auto-reply to a unique email address in a 24-hour period.|
- Before saving, click “Test Settings” to verify your entries. If the test is a success, the message “Connection completed successfully” will appear. If the test fails, go back and review your work until your test is successful. For help troubleshooting your mail settings, refer to the Inbound Email in SugarCRM section of the Knowledge Base or consult the IT department of your organization.
- Set the record’s “Status” to “Active” (when ready) and then click “Save”.
When a customer sends an email to email@example.com, Sugar will create a new case record and notify the assigned user as well as the customer (optionally) that a case has been created. The subject line of the received email will be imported as the case “Name” and the text in the email body will be imported as the case “Description”. The incoming email message will also be archived to the new case. If that email contains attachments, the attachments are included on the archived email record.
Note: To ensure that an account record is properly associated with the case at the time the case is created, the email address of the contact sending the email must be related to the account record (not the contact record).
To confirm that the email-to-case functionality is properly configured, navigate to the Emails module and click on the Settings button. Confirm that the new mail account appears in the Mail Accounts list on the Mail Accounts tab.
Send a test email to the email address you specified as the monitored group mail account. The next time the “Check Inbound Email Accounts” scheduler runs, Sugar will find the incoming message and create a case assigned to the appropriate user as determined by the distribution settings.
If Sugar does not create a case after you have sent a test email and you have confirmed that the scheduler has run, refer to the Troubleshooting the Inbound Email Scheduler article for assistance. If the scheduler is not automatically running, refer to the Troubleshooting Cron and Schedulers article for assistance.
By default, Sugar does not set the case Status field to a particular value. To tell Sugar to set the value to “New”, a user with developer-level access can follow these steps:
- In your Sugar file directory, locate the InboundEmail.php file in
- Make a copy of the file in this location of the custom directory:
- Note: You may need to create the InboundEmail folder inside the custom/modules directory if it is not already there. On the other hand, if there is already an InboundMail.php file located in the custom directory, skip the first 2 steps and continue with the next steps.
- Open the custom InboundEmail.php file and find the function called
- Under this line:
$c->name = $email->name;
Add the line:
- Save the custom file and its contents will supersede the core file you copied in step 1.