Email Administration

Overview

Sugar comes with many different email-related capabilities, many of which require an administrator to set up or configure. Email administration covers the system email settings, campaign email settings, email archiving, inbound email, and managing the email queue.

Email Accounts

Outgoing Email Accounts

There are three types of outgoing email accounts used in Sugar:

• System Email Account: The administrator sets up the system email account by configuring the System Email Settings. Sugar uses this account to send campaigns and email notifications such as password reset emails, record assignment notifications, and workflow alerts.
• Default User Email Account: A default email account is automatically created by Sugar for each user in Sugar. The default user account will use the primary email address stored in the user's profile. To use their default email accounts for sending email through Sugar, users must edit their profile and select "Sugar Email Client" as their outgoing email client. For more information on how users configure their user accounts, refer to the Emails documentation in the Application Guide. 
  Note: The users' default email accounts may be affected by the "Allow users to use this account for outgoing email" option in Admin > System Email Settings. If the administrator has enabled the option, users will not be able to configure their default email account and must instead utilize the system email account or create a new user email account. Users will see the system email account in the Outgoing Email Accounts list view with an asterisk to indicate that it is a system account.
• User Email Accounts: User email accounts can be created by all users and can consist of the user's personal email accounts (e.g., jane@example.com) as well as any shared email accounts. Shared email accounts allow a group of users to send outbound email messages using the same email account (e.g., support@example.com). If you have existing group email accounts that should be available to select when composing emails, it is recommended that you create a shared email account via Emails > Email Settings, making sure that it is assigned to the specific team(s) who can use the account to send emails. For more information on creating outgoing email accounts, refer to the Emails documentation in the Application Guide. 
  Note: The "Allow users to configure email accounts" option must be enabled in order for users to see the Create button to create new outgoing email accounts when they navigate to Emails > Email Settings.

Incoming Email Accounts

There are two types of incoming email accounts used in Sugar:

• Group Mail Accounts: Group inbound email accounts allow multiple users, such as team members, to view emails from an external mail account. When emails are addressed to your organization but not to any particular user, you can route them to a Group mail account such as support@example.com or sales@example.com. Users can subsequently distribute emails in the Group mail account to other team members. Emails received to a Group mail account will have no assigned user unless "Create Case from Email" has been enabled for the account.
  Note: Group Mail Accounts will only import unread messages from the mail server.
• Bounce Handling Mail Accounts: Bounce handling email accounts are configured to store campaign emails that are returned to the server, or "bounced" back to you due to incorrect email addresses or incompatible server settings on the receiving end. You can create a bounce handling inbox separately for each campaign, or you can create one that is common to all campaigns. The system tags every bounced campaign email with a unique identifier that enables you to identify the campaign.

System Email Settings

The System Email Settings section allows Sugar administrators to configure the system's outbound email settings as well as additional email and security options. Make any necessary changes in the sections below and click "Save" to commit the changes.

Outgoing Mail Configuration

This section applies to the system email settings. For help setting up the email accounts for individual users, please refer to the Emails documentation in the Application Guide.

The Outgoing Mail Configuration section contains details for sending email notifications, scheduled reports, workflow alerts, etc. Enter appropriate values for the following fields, keeping in mind that all required fields are marked with a red asterisk and must be completed prior to saving:

• "From" Name: The name the outgoing email will come from; for example, the name of your organization. Defaults to "SugarCRM".
• "From" Address: The email address the outgoing email will come from. Defaults to "do_not_reply@example.com".
  
  • If specifying a different address than the email address associated with the account you are authenticating, the email server being utilized may need to be configured to allow the email account to send email as the entered From Address. 
  • For more information on configuring "Send As" permissions with Gmail, refer to Gmail's Help documentation. 
  • For Exchange Online, enter only the authorized email address, as it cannot send emails using a different email address unless the organization's Exchange admin has configured the account to allow this. 
• Choose your Email provider: Click on the tile that corresponds with your mail provider (e.g., Google, Exchange Online) to populate provider-specific values. Refer to the table below this list for details about the fields shown for each provider.
• Allow users to use this account for outgoing email: Check this box if you would like users to be able to send emails using the same outbound mail account. If the option is not selected, users will still be able to use the outbound mail server to send emails by entering their personal mail account information in their user preferences. For more information on setting up the email settings in user preferences, please refer to the Email Settings section of the Getting Started documentation.

Once the appropriate mail server information is entered, you can send a test email to make sure it is configured properly. Click "Send Test Email", enter your email address, and send the test. If you receive the email, click "Save". If you do not receive the test email, re-enter the account information including the password to ensure it is all correct.

Email Options

The Email Options section provides some global options for email configuration. Check the box next to the desired options:

Note: Logged-in users must log out and back in for changes to the following settings to take effect.

• Assignment Notifications: When enabled (default), Sugar will send email notifications to users automatically when records are assigned to them. When assigning a record to yourself, you will not receive a notification of the assignment.
  Note: To receive notifications, users must also have "Notify on Assignment" checked in their user profile.
• Send notification from assigning user's e-mail address: Enable this option to have Sugar send notifications from the email address and name of the user who is assigning a record to another user. This option is disabled by default.
  Note: The SMTP server being used must allow sending from a different email address than the authenticated account and the email account may need to be configured to allow the Send As permission. For more information, please refer to the following articles:
  • Configuring "Send As" Permissions With Exchange
  • Configuring "Send As" Permissions With Office 365 
  • Configuring "Send As" Permissions With Gmail 
• Allow users to configure email accounts: Determines whether users can create new outgoing email accounts. When enabled (default), users will see a Create button when they navigate to Emails > Email Settings.
• Opt-out new email addresses by default: Enable this option to mark new email addresses added to Sugar records as opted-out by default. Email addresses that are marked as opted-out cannot receive campaign emails from Sugar. Please note that changing this setting will not affect email addresses already existing in Sugar. For more information on opted-out email addresses, please refer to the Emails documentation in the Application Guide.

Email Security Settings

The Email Security Settings section allows Sugar administrators to decide which HTML tags are allowed to be displayed in Sugar. The selected tags will not be allowed for viewing within Sugar. There are two options to mass set the tag selection:

• Select Outlook default minimum security settings: Select this option to automatically select every tag that Outlook also restricts. This will not strip the style tag which is used by default in Outlook. This option is selected by default.
• Toggle All Options: Select this option to either select all tags or deselect all tags.

After selecting one of those options you can individually select or deselect additional tags to restrict or allow the tags, respectively.

Related Contacts Emails

The Related Contacts Emails section allows administrators to enable or disable related contact's emails from appearing in the Emails subpanel and History dashlet for certain modules (Cases, Accounts, Opportunities). In order to have emails from related contacts appear in the Emails subpanel, simply mark the checkbox to the right of the module name (e.g., Opportunities). To disable related contact's emails from appearing in the Emails subpanel, uncheck the box for the specific module as necessary. Click "Save" to preserve the change.
  

Campaign Email Settings

The Campaign Email Settings section allows Sugar administrators to configure some backend settings for sending campaign emails. Select the appropriate values for the following fields:

• Number of emails sent per batch: When the "Run Nightly Mass Email Campaigns" scheduler runs, it will send out the specified number of emails for a single run. The default is set to 500. Some email servers have one or more of the following restrictions for a specific timeframe (e.g., hour, day, etc.): the number of unique recipients, how many times the same email can be sent to individual recipients, and the most common, how many emails can be delivered. This setting helps control the outgoing email to conform to these restrictions. For example, if your scheduler is set to run every hour, the number of emails to send per batch is set to 500, and you have 1600 emails to send out, starting at 2:00 AM the last batch of emails will be sent at 5:00 AM. Please check with your email provider to determine the proper level.
• Location of campaign tracking files: Campaign tracking files log responses from campaign targets. If you are running Sugar on an external network, select "Default" to accept the default location. However, if your Sugar instance is behind a firewall, then choose "User Defined" and specify the path to your external web server in the field below. The external web server must have the ability to connect to your Sugar instance behind the firewall. Ensure that you create a file named index.php to handle requests for three different types of entry points: campaign_trackerv2, removeme, and image, and place the index.php file in the path to your external web server. This index.php file must make the appropriate calls to the index.php file located in the root of your Sugar instance in order to properly record the activities in Sugar. For more information on how to set up a custom campaign tracker page, please refer to the Using a Custom Page For Campaign Trackers section of the Advanced Config Options documentation in the Administration Guide.
• Keep copies of campaign messages: Set this option to "Yes" to keep a copy of every email sent during a campaign. If "No" is selected, the template is saved and one copy of the email is stored in the Emails module. The email record will have an empty To field but the recipients will be visible in the email's related records subpanels. The default is set to "No".
  Note: Storing every email sent does take up space in the database and can reduce performance. We recommend setting this value to "No".

Make any necessary changes and click "Save" to commit the changes.

Email Queue

The Email Queue option in Admin is where Sugar administrators can monitor and perform actions on queued email. When sending a campaign, the emails are not sent immediately but are instead queued to be sent. Each queued email has a "Send On" date and time set by the campaign they are sent from. The scheduler "Run Nightly Mass Email Campaigns" takes the queued emails that are ready to be sent based on this date and time and sends them in batches. If an email fails to send from the queue for any reason it will be flagged as a send attempt and, by default, Sugar will not attempt to send that email for another 24 hours. Once Sugar reaches six failed attempts to send an email it will be deleted from the queue. In order to send a failed email sooner than the default 24 hours, you can perform a mass update to reset the In Process field. For more troubleshooting information, refer to the Troubleshooting Campaigns Failing to Send From Email Queue article. This section will cover how to use the email queue as well as the various actions and options available from within the email queue.

Viewing via List View

The email queue list view displays all queued email records meeting the current search criteria. To access the list view, simply click the Email Queue link on the Admin page. List view shows key email fields including links to the Campaign, Recipient, and Marketing Message records. For more information on viewing queued email via list view, please refer to the Email Queue List View section.

Searching Queued Email

The email queue list view includes a Basic and Advanced Search to help you locate records easily and effectively in a module-specific manner. Once the search is performed, the relevant results will be displayed in the Email Queue list view below. Please note that Sugar automatically appends the wildcard character (%) to the end of your search phrase. This allows the system to retrieve all records that start with the keyword entered in the search. If you would like to broaden the search, you can use the wildcard at the beginning of your text as well (e.g., %services). This will pull up any record that has the word "services" in the name, regardless of how it starts or ends.

For more information on using the various search methods as well as how wildcards are used in the different methods, please refer to the Search documentation.

Basic Search

Basic search offers a few, commonly used fields for a simplified search experience. From the Basic Search panel, you can click "Advanced Search" to access additional search functionality as needed.
The buttons and checkboxes available in Basic Search panel have the following functions:

• Search: Click the Search button or press your Return/Enter key to perform the search.
• Clear: Click the Clear button to clear all criteria from the searchable fields.

Once the search is complete, the relevant results will populate in the list view below the search panel. To see all queued email records to which you have access, simply click "Clear" and then "Search" to perform a blank search with no filters.

Advanced Search

Advanced Search offers a more in-depth search experience than Basic Search including additional fields, layout options, and saved search capability. From the Advanced search panel, you can click "Basic Search" for simplified searching.

The buttons, checkboxes, and dropdowns available in Advanced Search have the following functions:

• Search: Click the Search button or press your Return/Enter key to perform the search.
• Clear: Click the Clear button to clear all criteria from the searchable fields.
• Layout Options: Use the expandable Layout Options section to configure your list view. For more information, please refer to the Layout Options section of the Search documentation.
• Saved Searches: Save, recall, update, and delete searches that you use often. For more information, please refer to the Saved Search section of the Search documentation.

When you run a search, Sugar will return records matching all (as opposed to any) of the fields for which you have given a value. For example, if you enter a campaign name to search and a recipient name, Sugar will only return queued email records with matching both fields. Once the search completes, the relevant results will populate in the list view below the search panel. To see all queued email records to which you have access, simply click "Clear" and then "Search" to perform a blank search with no filters.

Email Queue List View

The Email Queue list view displays all queued email records meeting the current search criteria and to which your user has access. You can view the basic details of each email within the field columns.

You have the option to change what fields are displayed in list view by configuring your layout options in the Advanced Search. For more information on configuring your list view, please refer to the Layout Options section of the Search documentation.

Pagination

List view displays the current search results broken into pages that you can scroll through rather than displaying potentially thousands of rows at once. To the right just below the search panel, you can see which records of the total results set are currently being displayed. The two single-arrow Next and Previous buttons can be used to scroll through the records page-by-page. The two double-arrow First Page and Last Page buttons allow you to skip to the beginning or the end of your current results.

By default, Sugar displays 20 records per list view page, but administrators can change the number of records displayed via Admin > System Settings. For more information on changing the number of displayed records, please refer to the System documentation in the Administration Guide.

Checkbox Selection

You can perform several actions on queued email records directly from the list view by first selecting the desired records. To select individual queued email records on the Email Queue list view, mark the checkbox on the left of each row. To select or deselect multiple queued email records on the list view, use the options in the checkbox dropdown menu:

• Select This Page: Selects all records shown on the current page of results.
• Select All: Selects all records in the current search results across all pages of results.
• Deselect All: Deselects all records that are currently selected.

Actions Menu

The Actions menu to the right of the checkbox dropdown allows you to perform various actions on the currently selected records.

The options in the Actions menu allow you to perform the following operations:

Column Sorting

List view provides the ability to sort all of the current search results by a field column in either ascending or descending order. To sort by a field or switch the sort direction, click the column header noting that the fields which allow sorting will have a pair of arrows. The list view may be sorted by only one column at a time. You can also set a default order-by column using the layout options in Advanced Search. For more information on setting a default column sort, please refer to the Layout Options section of the Search documentation.

Deleting Queued Email

If a queued email is invalid or should no longer be sent, it may be deleted from the list view. The list view allows for mass deleting multiple records at once. Deleting queued emails will not delete the campaign or target, but will remove the instance of this email so it will not be sent.

Mass Deleting via List View

Use the following steps to delete one or more queued email records via the list view:

1. Navigate to the Email Queue list view by clicking the Email Queue link on the Admin page.
2. Use the Basic or Advanced Search to find the queued email records you wish to delete.
3. Select the desired records individually or using the checkbox dropdown's options.
4. Choose "Delete" from the Actions menu.
   
5. A pop-up message will display asking for confirmation. Click "Ok" to proceed.

Due to PHP memory limitations on the server, there may be occasions when the application times out while deleting a large number of queued email records. If you encounter an error when performing this action, we recommend selecting the records in smaller batches.

Mass Updating Queued Email

Mass Updating allows users to make the same change to multiple queued email records at once from the Email Queue list view. Currently, only fields with the data type of date, datetime, dropdown, multiselect, and radio may be altered during a mass update. Due to the PHP memory limitations on the server, there may be occasions when the application times out while mass updating a large number of queued email records. If you encounter an error when performing this action, we recommend selecting the records in smaller batches.

Use the following steps to mass update queued email records from the list view:

1. Navigate to the Email Queue list view by clicking the Email Queue link on the Admin page.
2. Use the list view's Basic or Advanced Search to find the queued email you wish to modify.
3. Select the desired records individually or using the checkbox dropdown's options.
4. Choose "Mass Update" from the Actions menu.
   
5. Scroll to the Mass Update panel and set values for the fields you wish to alter.
   
   Note: After an email has failed to send, setting In Process to "No" will flag the email to attempt to send again. Otherwise, the email will not attempt to be sent again until 24 hours have passed. Optionally set the Send Date to configure when the email should be attempted again.
6. Click "Update" to save the changes to all of the currently selected queued email records.

Sending Queued Email

Email in the queue will be automatically be sent out in batches by the "Run Nightly Mass Email Campaigns" scheduler. For more information on setting up and configuring scheduler, please refer to the Schedulers documentation in the Administration Guide. Alternatively, you can manually send a batch of emails in the queue. The amount of queued email that will be sent is equal to the "Number of emails sent per batch" value specified in the Campaign Email Settings.

Use the following steps to manually send a batch of queued emails from the list view:

1. Navigate to the Email Queue list view by clicking the Email Queue link on the Admin page.
2. Choose "Send Queued Campaign Emails" from below the list view.
   
3. Sugar will then send a batch of queued email whose Send On date and time is equal to now or in the past.
   Note: If an email fails to send it will not be tried again for 24 hours.

Selecting specific records and searching for specific records will not determine which queued emails will be sent. This process will send a batch of emails that are queued to be sent in order by the Send On field. For more information on setting the batch amount, please refer to the Campaign Email Settings section. 

Note: If your batch size is set high and you have a lot of queued email, this process can take a while to run through a single batch.

Creating via Duplication

You can also create a new group mail or bounce handling account by duplicating an existing inbound email account record. The copy option is useful if the inbound email account you are creating has similar information to an existing inbound email account.

Use the following steps to create an inbound email account by duplicating an existing record:

1. Navigate to an inbound email account record's detail view.
2. Click "Copy".
   
3. The displayed edit view is pre-populated with the original account's values. Update the necessary fields, then click "Save".
   

Email Archiving

The Sugar Email Archiving service allows users to easily archive email to Sugar records simply by sending the email to a special email address. The email archiving service monitors the email address and imports the email into your instance of Sugar and links related records without the use of a plug-in or other syncing process.

This section explains how the administrator can enable the Sugar Email Archiving service. For complete steps to use Sugar Email Archiving once it is enabled, please refer to the Emails documentation in the Application Guide.