2.4 Email - Copyright 2021 Agiloft Inc. All Rights Reserved.
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
2.4 — Email © Copyright 2021 Agiloft Inc. All Rights Reserved. HELP-31Mar2021
CONTENTS
1. Working with Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 Sending Emails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2 Viewing Past Emails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.3 Creating and Updating Records by Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2. Email Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.1 Configure the Email SMTP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.2 Inbound Email Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.3 Email Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.4 Outbound Email Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.5 Configure Group Permissions for Sending Emails . . . . . . . . . . . . . . . . . . . . . . . 36
2.6 Email Marketing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.6.1 Email Marketing Tables and Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
2.6.2 Automated Email Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
2.7 Email Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
3. All Communications Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Working with Email
Emails are an essential part of most implementations. Email can be sent from any record in the system, and
they can be received and linked to a record. Most emails are automatically sent by rules, but emails can be
manually sent to individuals and even in bulk. Emails that are sent from the system or received with a linked
record are also accessible in the record, which makes it easier to keep track of past communications and
discussions.
For information about sending and drafting emails, including details about using the features of the email
editor, see Sending Emails. This information also applies to creating email templates. Emails and email
templates can include lots of information from the system, so make sure you understand all the possible
options so you can take advantage of them.
For more information about tracking and reviewing past emails, see Viewing Past Emails.
When you send an email from the system, you can also define the return address to use if the recipient replies
to the email. For more information about email recipients, see Sending Emails. For more information about
what happens when someone sends a reply to the system email address, see Creating and Updating Records
by Email.
Email options depend on your permissions. If the information in an article doesn't match what you
see, or if you can't access the option to send email at all, you might not have the necessary
permissions.
Sending Emails
© 2021 Agiloft Inc. 3
Sending Emails
Emails can be sent from Agiloft automatically behind the scenes or manually as needed. It is common for
most outgoing system emails to be automatically sent behind the scenes when certain criteria are met, using
rules. For example, you could use a rule to send a notification email when a contract changes status, or when
a user is assigned to a record. Administrators can find more information about automating emails in Email
Actions.
Emails that are sent from Agiloft are saved and organized, so you can find past communications based on the
records or people they involve. For example, you might be working on a contract record and use the email
icon to send it to a colleague to ask for more information. Emailing the record from inside Agiloft allows you
to link directly to the record and also makes it easy to see all emails related to the record in the future. For
more information about viewing past correspondence, see Viewing Past Emails.
When you send an email from Agiloft, you can create it from scratch or use an email template. Email
templates are configured by administrators for each table. You can also save your own email templates if you
have the necessary permissions, so you can reuse emails you send frequently that may not be useful for
others. For information about managing email templates, see Email Templates.
The Agiloft email client allows you to make use of some of the most powerful features of the system, such as
templates, formulas with variables, searches, the Text editor, linked records, file attachments, hyperlinks, and
table fields. Permission to create emails and email templates, and to publish templates to other users, is
granted for each table.
Example
In the example below, the email was created from the "Email assigned team that Case is approaching
SLA Due date" template. It is linked to two records in the Support Cases table. The subject uses two
formula elements: $id and $formula($sla_due_date). The email was automatically addressed to
the Assigned Team Manager. It contains a hyperlink to edit the record, and all the affected fields have
been included at the bottom.
Send an Email
© 2021 Agiloft Inc. 4
Send an Email
To send emails outside of automated workflows, users can manually send new messages from several places:
Within a record, click the Email icon, or click New on the Emails tab if the Emails tab is configured for the
table.
In the table view, select one or multiple records. Then use the Email drop-down in the action bar to
select Send Email or the name of an existing email template. There might not be any email templates
listed if there are no templates for the table or if they aren't marked Active for your team, or if you don't
have permission to use email templates.
In the Communications tab of the left pane, select New > New Email.
After you use one of these options to manually begin an email, you can always insert an email template from
inside the email editor by selecting Insert > Populate from template. This option lets you select any email
template you have permission to use, even if it isn't marked Active.
Create an Email Template
Email templates use the same content editor tools as standalone emails. Follow these steps to create a
template instead of a standalone email.
1. In the table view, select the Email icon and then choose Manage Templates. This opens a list of email
templates for the table.
2. Click New to open the Email window.
3. Select the Heading tab and:
a. Enter the Template Name.
b.
© 2021 Agiloft Inc. 53.
b. Add a Description.
c. Select whether the template is visible for users with permission to view published templates.
d. Select the teams for which the template is active.
4. If necessary, select the Options tab to configure additional options.
5. Select the Message tab to reopen the email editor. Create the email template using any of the features
described in this topic.
6. Click Finish to save the template. It will be added to the list of available email templates.
For more information about managing email templates, see Email Templates.
Email Editor
The main part of the Email window is an HTML Text editor that allows you to create, edit, and format text and
insert pictures, hyperlinks, and even tables into the email. The HTML drop-down allows you to create emails in
the following ways:
As HTML, via the What You See Is What You Get (WYSIWYG) elements around the window.
As HTML directly from source. This removes the WYSIWYG elements from the top of the window and
processes the HTML markup.
As plain text. This removes the WYSIWYG elements from the top of the window, and it doesn't process
any HTML markup.
Recipients and Senders
The fields for adding recipients, senders, CCs, and BCCs are above the subject line of the email. To change the
default From and To options, hover over the arrow and select one of the email addresses from the list.
© 2021 Agiloft Inc. 6The Reply-to option allows you to define a different address to use when someone responds to the sent email.
For example, you might show a team email as the From address, but have the reply sent directly to your email
address. You can also use this option in conjunction with inbound email settings to take action based on the
response. For more information about receiving emails and email responses, see Creating and Updating
Records by Email.
Select Recipients
1. Select the Recipients drop-down next to the To field to see the options to search for or add email
addresses.
2. To send the email to a system-defined address:
a. Select the search type, such as Users and Teams.
b. Click the look-up icon to locate the address.
c. Select and import the address into the list of recipients.
3. To send the email to an address that is not in the system:
a. Select Addresses.
b. Enter the email addresses in a comma-separated list.
You can use multiple search options for one email. Whenever possible, it is better to send email to a person
defined in the system, rather than manually typing their email address. This allows users to see all the
information they have permission to see, whereas adding a user's email address manually gives them access
only to information guests can see.
Select CC and BCC Recipients
1. Hover over To to open a drop-down, then select CC or BCC.
2.
© 2021 Agiloft Inc. 72. Choose the recipients as above.
Sending an email to too many people at once can trigger spam filters. When sending an email to a
large number of recipients, Agiloft limits the number of emails it can generate per transaction. By
default,, Agiloft can generate only 250 unique emails per transaction.
For example, if you have 350 unique recipients, Agiloft uses the first transaction to generate emails for
the first 250 unique email addresses. After a short interval, typically one minute, Agiloft then uses a
second email transaction to generate emails for the remaining 100 unique email addresses.
If you have access to the Admin Console, you can adjust this number using the Max amount of unique
user emails generated per time global variable.
Automatic Recordkeeping
When an email is sent, the system automatically stores a record of the email in the All Communications table
and populates the record with the sender, recipient, and linked record information, if available.
The From Login and From Company fields are automatically mapped from:
The sender's user record, if the email was sent by a user
The sending information configured for the rule or outbound address, if the email was sent by a
rule
The To Login and To Company fields are automatically compared to the contacts in the system. If any
matches are found, the contact information is mapped to the email.
© 2021 Agiloft Inc. 8The linked record is mapped to the Background Details tab of the email record, if the email was sent
from a record in a table. Linked record identifiers are built by saving the table name and record ID and
combining them into a Linked Record hyperlink.
If the email is sent from the Communications tab instead of a record, the email can be found in the user's sent
email list and in the contact record of the recipient.
Formulas in Emails
Formulas can be used in the email subject line and body to include information about the record, recipient,
and more. To add a formula, position the cursor where you want to insert text and do one of the following:
Select Insert > Variables
Click Formula Help and click the formula or variable you want to enter
Manually enter the formula as text into the header or body
Formulas can enable you to populate emails with data from the knowledgebase. For example, in the Support
Case email template, formulas are used to populate...
The recipient name - $end_user_name
The ticket ID and summary - $id, $summary
© 2021 Agiloft Inc. 9The ticket notes - $additional_notes_latest
Other ticket details such as Date Created, Customer Name, Status, Priority, Type of Issue, and
Description.
Example
In this example, formulas are used to populate the recipient's name, ticket ID and summary, and the
latest notes.
In some configurations, you might use a formula to insert text that itself includes a formula. For example, you
might include $resolution_text in a Service Request email template, but the Resolution field might also include
$working_hours_to_close. If you need to use email templates that insert nested variables, you can configure
your KB to resolve both layers of variables by setting the iterative_email_body_formula_resolver global variable
to Yes.
Table Fields in Emails
1. To insert fields from the table and record into the email, open the Include Fields window by either:
Selecting Insert > Fields from
Clicking the link at the bottom of the Email window, next to Fields Included
2. Select Yes to Include fields from , then choose whether to insert the fields as inline text or
as an attached file. If the fields are inserted as inline text, they appear below the text body.
3. Select which fields to include, and whether to only include fields that have some content.
4. Click Finish.
© 2021 Agiloft Inc. 10When composing emails, you can use formulas, included fields, or both. You might use formulas to
include the most important information in-line in the email body, and then include some fields to offer
the recipient additional information if they need it. When you use Fields Included, the fields are
automatically formatted in a table, and you can automatically hide fields that don't have any content.
File Attachments
Files can be attached to emails manually, or you can select File with Versioning fields in the record to include.
Since versioning is not needed for emails, it is disabled in the field. Follow the steps in the Table Fields in
Emails section to include file fields.
Attach Past Communications
It's possible to import any email in the All Communications table into the current message. To do this:
1. Select Insert > Message to import. The All Communications table opens in a dialog box.
2. Locate the relevant message and click Import/Replace.
This inserts the message content as HTML text into the Email editor. You can add other email body content
and edit your draft before sending the email.
Hyperlinks in Emails
Use hyperlinks to allow email recipients to open a record directly from the email. This makes it easy for
recipients to approve or reject changes, add notes, answer questions, review details, locate past
correspondence, and much more, without manually logging in to the system and navigating to the record.
To insert a hyperlink to the current record:
1. Select Insert > Include a hyperlink to edit the .
2. In the Hyperlink window, enter the hyperlink text.
3. Select whether to edit or view the record when the link is clicked. If you make the link view-only, users
with the necessary permission can still click Edit to make changes to the record.
If the record opens for editing, select the browser redirect behavior when the user clicks Finish or
Cancel. You can set specific redirect addresses here, or control the default Finish and Cancel
URLs with the Exit URL and Cancel URL global variables.
© 2021 Agiloft Inc. 11If the record opens for viewing only, select the redirect behavior when the record is closed. The
default redirect address for closing a record is also controlled by the Exit URL global variable.
4. Alternatively, you can configure the hyperlink to automatically populate a field without requiring the
user to view or edit the record at all. With this option, the user can be redirected to a different URL. For
example, you might redirect the user to a page that shows a confirmation for their action.
5. Select the Start and Expiration times of the hyperlink. You can use:
No start or expiration time. If you do not specify an expiration date here, the value in the Hotlink
Age or Email Marketing's URL Age global variable determines the default expiration date.
An exact date and time.
A calculation of the time created plus a defined number.
You can enable SSO from hyperlinks in emails after you complete the steps in the Single Sign-on topic. If a
user encounters an error while attempting to access Agiloft through a hyperlink, they are brought to the URL
defined in the Error URL global variable.
In addition to these configurable record hyperlinks, hyperlinks can be added manually, either by clicking the
link icon in the WYSIWYG editor or by editing the source HTML. Read the Hyperlinks topics to learn more
about their syntax and functionality.
If you are creating company branding from a hosted server, or you believe your DNS is misconfigured
or has some other installation issue, you might need to edit the value of the Hotlink Server Root URL
global variable for hyperlinks in emails to work.
URL Encryption
Hyperlinks sent from within Agiloft messages are automatically encrypted, so it is not possible to use them to
obtain user login details; however, a malicious user could still access the system through the link. For that
reason, when sending links from Agiloft in emails or other messages, you can enforce authentication and
restrictions when users click through into the system, generally in one of two ways:
First, click the Setup gear in the top-right corner and go to Access > Configure Hotlinks. This contains
the settings for requirements for user authentication via hyperlink. Hyperlinks can be set to always
require authentication, or to only require authentication the first time they are clicked.
Second, go to Setup > Access > Automatic Login Hotlinks. This enables you to encrypt any hyperlink
that you manually constructed, that can be shared with users. For more information, see Encryption
keys.
Email Options
Clicking Options at the top of the Email window opens some additional settings for the email:
© 2021 Agiloft Inc. 12CC one copy of the email to Users. This is primarily used in email templates as a way to always include a
person or team as a CC when other users send the template.
Collate Results. This option appears when multiple records are selected. If the same user is selected as
a recipient for more than one of the records, choosing Yes will collate all the results and send them as a
single email, rather than as multiple emails.
Include encrypted ID in subject line. This enables the system to parse responses so that the correct
record can be updated.
Enable field parsing for replies. See Email Parsing for more information.
Include Hidden Code for Truncating replies. This inserts a hidden code into the email so responses can
be truncated. The system will strip the original email message identified by the code, preventing overly
long email threads.
Email marketing options. These options only appear if Email Marketing is enabled for a table.
Send Emails in Bulk
You can send the same template email to several records at once, each with the details from the selected
record. The sent email will be linked to each record, appearing in the Email tab and in History.
1. In the table view, select the records in the list.
© 2021 Agiloft Inc. 132. In the email icon drop-down, select the template name or Send Email.
3. Make any changes desired in the email editor.
4. Select the To and From contacts for the email. You can use linked fields to automatically select a certain
user based on the record information, such as the Assigned Person or Created By user. To send emails
to additional recipients, hover over To and select CC or BCC.
Email Automation
While it is possible to create and send emails manually, emails are frequently sent as part of a rule, an action,
a workflow, or a schedule. Automated emails will generally use a template with formulas to populate the entire
email based on the relevant system information. Automated emails can serve many varied purposes.
Example
If a Support Case status changes to Complete, an action can be added to the rule to send an
email notification to the record owner.
A chart tracking resolved tickets can be emailed to team leaders whenever it is created, at the
end of the day.
If an Adobe Sign envelope is signed by the recipient, the sender can be automatically notified by
email.
Automated emails can be set up in the following ways:
The Reports wizard contains a Schedule tab where you can decide the frequency of the report, whether
to distribute the report by email or by writing it to the disk, and the email addresses it should be sent to.
The Action type Email/SMS Action can be used with action buttons or rules.
© 2021 Agiloft Inc. 14Viewing Past Emails
Emails sent to and from the system are stored, so you can find past correspondence and see what records
were linked. While the data is stored in the All Communications table, past emails are accessible from many
places in the system to make it easier to find what you need.
Record View
Most emails relate to a specific record in a table, and most record layouts include an Emails tab with a related
table that shows all email communications linked to the record. This is usually the best place to start when
looking for past communications.
Communications Tab
In the Left Pane, the Communications tab shows emails you sent or received for any record in the system,
based on your login credentials. Communications that aren't related to records can be sent and received
directly from the Communications tab.
When you navigate to the Communications tab, your view is filtered by three things:
Group permissions for the All Communications table.
A special group permission filter on the General tab of the Group Permissions Wizard that further
restricts what can be viewed through the Communications tab. For more information, see the All
Communications topic.
The default searches that run when accessing communications, such as Email Inbox or Sent Emails.
Because these are only searches, you can click Show All to see all communications permitted by the first
two filters.
This view is actually a filtered view of the All Communications table, which contains records for all emails sent
to and from the system. The Email Inbox and Sent Emails links are saved searches for the All Communications
table. This tab can be hidden using group permissions.
All Communications Table
© 2021 Agiloft Inc. 15All Communications Table
All emails are stored in the All Communications table. This table is used to create the Communications tab and
the Email Inbox and Sent Emails saved searches. They can be changed, and other searches can be
created. Users only see saved searches that their groups have permission to access and that they have chosen
to display in the left pane from the Manage Saved Searches screen.
By default, the All Communications table is hidden from the navigation menu for all users because it
eliminates the specific table filters that control what users see. If it must be restored, an admin can
click the Setup gear in the top-right corner and go to Tables, select All Communications, and click
Unhide to show the table for the admin group only. To show the table to other user groups, edit the
group permission settings at Setup > Access > Manage Groups.
Creating and Updating Records by Email
Create and update records from outside the system by sending emails. You can create records in a table by
sending an email to the table's configured inbound email address, if the inbound address is configured to
allow record creation in general and you specifically have permission to create records in the table. If you
receive an email from the system regarding a record, you can reply to that email to make updates to the
record, or simply record your response in the system, depending on how your system is configured.
For example, if you receive an email regarding a support case with a request for more detail, you can reply to
the email and supply the information requested.
When an email is sent by the system from a record in a table, the table name and record ID are
encrypted into the header and the subject line of the outbound email. When an email is received by
the system, it looks for the encrypted ID in the subject or header to determine if it is a reply regarding
an existing record. If it is, then the email is treated as a record update. If no encrypted ID is found, it is
treated as record creation, and the system checks whether record creation is enabled.
© 2021 Agiloft Inc. 16Processing Updates by Email
If the email is an update to an existing record:
A communication record is created and linked to the record from which the original email was sent, so
the new email appears within that record. For example, if the original email was sent from a support
case, and the customer replies with more details, the communication record is linked to the support
case.
The email body and attachments are typically mapped into an Append Only field and Attached File field
in the linked record. How the parts are mapped is defined in the inbound account setup on the Email
Updates tab and the Email Parsing tab.
Creating Records by Email
If an email is received with no encrypted ID, permissions determine what happens next.
If record creation is permitted and the sender’s group has permission to create a new record, or the account
setup grants guests permission to create a new record:
A new record is created that maps the content of the email according to the options on the Record
Mapping tab of the Inbound Email Setup.
A communication record is created and linked to the new record.
If the conditions are not met, the record is discarded.
If you want unknown users to have permission to create records, be sure to select a user account on
the Access tab that has permission to create records in the desired table. The Access tab is part of the
Inbound Email Accounts setup.
Email Configuration
For a general overview of emails in Agiloft, see the Working with Email topic. This topic addresses how to
configure the email server, email processing, and automated emails.
When setting up email integration, the order is important. When you set up outbound email, you want to have
inbound accounts set up already so you can use them as the default outbound from address. The
recommended setup order is:
1. Set up the SMTP server and send a test email.
2. Set up inbound email accounts for each table in which records are to be created or updated by email.
Note there are extra steps for Microsoft Exchange and Office 365 Email Setup.
3. Set up outbound email behavior for each table that will be sending email notifications.
4. Configure group permissions to allow groups to send emails.
5. Check group permissions on the All Communications/Email table to ensure that groups which need to
view emails can do so.
6. Customize default views on the All Communications table if desired.
© 2021 Agiloft Inc. 17Configure the Email SMTP Server
To use email with Agiloft, you need to have an email server set up.
If you are using Agiloft's hosted service, the outbound email server is already configured. However,
you may want to set or change the default outbound address for your system.
If you aren't using Agiloft's hosted service, or if you want to adjust the default outbound address for your
system:
1. To configure the Email outbound SMTP server, go to Setup > Email and SMS > Configure Email Server.
2. Review the SMTP server listed. By default, the SMTP Server is set to localhost, which will work if
Sendmail is installed on your server. Otherwise, you will need to identify an SMTP server to use.
3. Review the SMTP options selected below the server address and make adjustments if necessary. The
SSL/TLS option is used if the server supports encryption, for maximum security. If this does not work,
the STARTTSL option often works, as it negotiates security after the initial exchange.
4. Enter the SMTP login and password, which is the email address and password of the default SMTP
account. The login should not include the full address, only the part that precedes the @ sign.
5. Define the Default outbound email address for your system. The outbound address does not have to
be a functional email address, but it must be formatted like an email address for validation purposes. If
you do plan to send emails using this address as the From address, it's best to match the email server's
domain so that the emails are less likely to be marked as spam.
If the outbound email is a Gmail address, the default behavior for Gmail is to treat Agiloft as an
insecure app and block the connection. Log into your Google settings account and enable
insecure apps. For more information, see Allowing Less Secure Apps to Access Your Account.
6. Test your email setup by entering your email address in the text box and clicking Finish.
If you don't receive a test email, review your settings and retest.
What happens if the SMTP connection fails?
By default, if the SMTP connection fails, Agiloft caches failed emails for 5 days and attempts to resend them
every 30 minutes. After 5 days of failed attempts, Agiloft no longer attempts to resend that email. To change
the default behavior of the system:
Edit the amount of days that Agiloft waits before no longer attempting to resend a failed email using
the Do not resend old letters global variable.
Edit the frequency (in minutes) at which Agiloft attempts to resend failed emails using the How many
minutes to wait before resending failed letters global variable.
© 2021 Agiloft Inc. 18Inbound Email Accounts
Emails sent to the Agiloft system can be configured to create or update records. It's generally a good idea to
set up at least one inbound account for each main process table. This way, if the system sends an email and
the recipient replies, their reply will come back into the system. You can set up multiple email accounts, one or
many for each table, and define individual behaviors for each.
It's also useful to use the table's inbound account as the default outbound account for emails sent from that
table. This makes it easy for users to respond to system emails to update records or add correspondence.
Inbound accounts are not required for the system to function, but it's a good idea to maintain some in
case anyone sends email to the system. If you don't want to use inbound accounts, you can set up an
automatic response such as, "You have emailed a non-working account. Please submit your request
online."
Configuring Inbound Accounts
The Inbound Email wizard is used to set up email accounts that handle replies to outbound emails and any
emails sent directly to the system. These are usually used to create new records or update existing records by
email. Set up at least one inbound account for each main process table in case anyone replies to outbound
emails from the table.
In many cases, you'll want to create multiple inbound accounts to handle different situations and make the
table work more smoothly. For instance, you might set up a billing@xyz.com email account that maps to a
Problem Type of Billing, and a newaccount@xyz.com account that maps to a Problem Type of New Account
Setup.
Follow these steps to configure an inbound email account:
1. Navigate to Setup > Email and SMS > Configure Inbound Email. You will see a list of any existing
inbound email accounts for all tables.
2. Click New to open the configuration wizard.
3. In the Table tab, select the table that will receive the inbound email, then click Next.
4. Navigate through all the tabs listed below. Remember that your changes won't be saved until you click
Finish on the final tab.
If you reuse the same inbound email address in multiple tables, emails sent to that address might
create records in each of those tables. Be strategic in choosing whether to share an inbound account
across tables or create individual accounts for each table.
© 2021 Agiloft Inc. 19Server
Here, define the email server.
1. Choose the type of email server from the options given:
POP3. Choose this option if your email server uses POP3.
IMAP. Choose this option for IMAP, MS Exchange WebDAV, and Outlook Web Access. For
Exchange, refer to the detailed instructions in the wizard to determine the appropriate syntax
depending on your version and specific configuration.
2. Enter the server name or IP address.
3. If necessary, enter a custom port value. The value is set automatically based on the other settings you
choose, but you can overwrite it if needed.
To configure a Gmail account, see Google Help for information on the IMAP/POP3 account settings.
For Gmail to work with Agiloft, you also need to allow less secure app access in your Gmail account
settings.
To configure an Office 365 or Microsoft Exchange account, you need to complete additional setup on
the Server and Account tabs. For details, see Microsoft Exchange and Office 365 Email Setup.
Account
The system status message in the Account tab tells you whether the connection to the Inbound server is
successful.
To configure an Office 365 or Microsoft Exchange account, you need to complete additional setup on
the Server and Account tabs. For details, see Microsoft Exchange and Office 365 Email Setup.
To continue setup:
1. Enter the Email address.
2. In the Email Account field, enter the complete username, which may include a domain or other
information.
It is possible to use a shared mailbox for the inbound account. Shared mailboxes are typically
owned by a non-shared account that is used for authentication. Use the shared account in the
Email field, use the password for the owner account in the Password field, and combine the two
accounts in the Email Account field in this form: accountowner@example.com
/sharedmailbox@example.com.
3. Enter the password for the authenticating account.
4. Select the Activity desired for this account. You can use this to disable active use of this account.
5. For IMAP accounts, if desired, enter the folder path where incoming emails should be filed.
6. Click Next.
It is possible to use a shared mailbox for the inbound account. Shared mailboxes are typically
© 2021 Agiloft Inc. 20Record Mapping
To let records be created from inbound emails, configure the settings on the Record Mapping tab. Define
which fields are used to store the email data, including the subject of the email, sender's email address, email
body, and any attached files.
1. Define how to handle the sender and recipient values, including the name and email address of the
sender and the people on the To and CC lines. Email addresses can be stored separately from the
name, which can be useful to prevent errors due to name-sensitive email recognition.
If you use the email address to try to match a contact record's Email field, select the option to
strip out all text other than the email address.
2. Select options for storing the message, attachments, and images.
3. Select any fields you want to set automatically. For example, you might configure an address for urgent-
outage@yourcompany.com to automatically set Priority to 1.
4. Click Next.
Email Updates
Choose if and how records are updated by email.
1. Select where to store the body of the email. It's usually best to append the body of the email into an
Append Only field. This way it is native to the table and can be sent with the other fields in an email
notification. For instance, you can create the following email notification: "An email was received from
$updated_by and here is its content: $additional_notes_latest."
2. Determine whether to include quoted content. If you choose to remove quoted content, the system
truncates any part of the email that follows the hidden code, if a hidden code is configured in the
outbound settings. This is intended to remove the email conversation quoted at the bottom, to avoid
duplicating messages over and over in a long thread.
3. At the bottom, select options to determine where attached images and files are stored.
4. Click Next.
© 2021 Agiloft Inc. 21Email Parsing
Email parsing makes it possible to update specific fields based on text held in the email body. When using
parsing, you must define a delimiter string the system will use to start and end parsing. For example, if "Agiloft
Details" is defined as the delimiter, the following email will set the Manager, Comments and Priority fields in
the record:
For more information, see Email Parsing.
The heading delimiter must contain the Language Code defined in the wizard.
1. Select the Enable field parsing for inbound email checkbox.
2. In the text field, enter the delimiter string the system will use to start and end parsing. In the example
above, you would enter Agiloft Details.
3. Select the language.
4. Determine whether parsing replaces or adds to the field values set by your configuration on previous
tabs.
5. Select options for handling errors, invalid fields, and permission issues. For each option, you can also
choose to email administrators when the issue occurs.
6. If you chose to email administrators about any issues, complete the fields to set the email address for
the administrators and the contents of the message.
7. Click Next.
© 2021 Agiloft Inc. 22Access
This tab defines options such as whether or not record creation by email is allowed, what to do when the
sender is not recognized, who to notify if an email is rejected, and how long emails are left on the server after
they have been retrieved.
1. In Record Creation, select or clear the Enable creation of records by email checkbox.
2. If you clear the checkbox, you can optionally select the option to send a reply when someone attempts
to create a record by email. For example, you might send a message saying, "Records cannot be created
by email. Please log in to the system to create a new record."
3. Next, determine what happens if the email address trying to create a record doesn't match an email in
the system. You can either:
Create a new record using a specified existing user's account. You can also select this option with
an additional limitation to process emails only from addresses with a specified domain. To use
this feature, enter the allowed domains in the field, separating each domain with ;.
If you allow emails from unknown users, choose your guest account and its group
permissions carefully. Be sure the guest group has "create own" access to the table and
the fields you have mapped. Email updates do not check the permissions of the sender;
they are applied to the correct records without limitation. This is to enable people who
were cc'd about the original ticket to be able to successfully reply to the system even if
they are not users.
Discard the email. This way, only existing users can create records by email, and they can only do
so from an email address linked to their user record.
4. Complete the same options for record updates.
5. If desired, select the option to forward discarded emails and specify an addressee, message content,
and whether to include attachments.
6. Finally, determine how long to keep emails on the server. It's generally best to leave email on the server
for one or two days to allow time for troubleshooting.
7. Click Next.
Filters
Use filters to prevent email loops and spam from automatic email replies. For example, if a user has an
automatic out-of-office reply set up and the system sends the user an email, the automatic reply can trigger
additional system responses endlessly.
© 2021 Agiloft Inc. 231. Select the options for handling bounced emails. In most cases, all the options in this section should be
selected to prevent loops that generate records endlessly. If you choose to clear any of the checkboxes,
make sure to carefully check all inbound processing and automatic responses beforehand.
2. If desired, disable automatic responses to email from specific addresses or containing certain phrases.
If an automatic response is disabled, the system still creates a record based on the email, but no
response is sent to the sender.
3. If desired, discard email from specific addresses or containing certain phrases. This prevents a record
from being created and simply discards the email.
4. Discontinue auto-responding by setting the number of messages that can be processed from a single
address in a specified time frame.
5. Keep email subjects tidy by truncating Re: and Fwd: subject prefixes after a specified amount.
6. Finally, if you want to apply your Filter changes to all inbound accounts, you can select the Update all
inbound email filters checkbox.
7. Click Finish to save your changes.
If you suspect a loop has occurred, first inspect the records that were automatically updated and then
update the settings on this tab.
Checking Inbound Accounts
By default,, Agiloft checks inbound email accounts and downloads new messages every minute. New
messages are copied into the Communications table for the associated email account's table. When an email
is received by the system, it looks for the encrypted ID in the subject or header to determine if it is a reply to
an existing record. If it is, then the email is treated as a record update. If there is no encrypted ID found, it is
treated as an email that will create a new record if record creation is enabled.
Depending on the contents of a particular email, the following processes occur:
1. If a Record ID is encoded in the subject or header, the system recognizes the email as an update to
that record. Depending on your email settings, parts of the email can be copied to the Additional Notes
field of the record, and change the Updated By field. When a record ID is encoded in the email, Agiloft
does not check the permissions of the sender. This allows external users to respond, for instance if they
were cc'd on a ticket, and saves their update to the record.
© 2021 Agiloft Inc. 242. If no Record ID is encoded and the sender's email matches a user in the Contacts table, and
record creation is allowed for that inbound account, and the user has the appropriate permissions, the
system creates a new record under that user's name.
3. If no Record ID is present and the sender is not recognized, the system ignores or rejects the email,
or creates a new record under a user account that you specify during setup. Guest accounts are usually
used to create new records in this case.
You can alter the frequency that Agiloft checks for inbound emails using the Checking frequency for inbound
emails (minutes) global variable.
Troubleshooting Inbound Accounts
The outbound email header contains encrypted information about the table and record ID from which it was
sent. Because MS Exchange strips out headers when sending internal emails, we also add this encrypted
information to the subject line of emails as a backup.
The outbound email header also contains complete details on how and why the email was sent, such as server
URL, KB, table, and rule or workflow ID that initiated the email. This information is displayed in the
communication record. It can also be viewed in an email received in Outlook by clicking View > Options on
older releases of Outlook, or File > Properties and scrolling through the Internet Header display. This is useful
when testing or troubleshooting when you receive emails without knowing why.
Inbound Email Security
You do not have to let people create records via the inbound email account. As described in the Access
section, you can limit record creation to registered users or email addresses in certain domains, or prevent
anyone from creating records this way. When a new email is received that isn't processed as an update, the
system looks at the sender's address and checks it against user records for a match in any email field. If it
finds one, it applies the user's group permissions to the request to create a record; if it doesn't find a match, it
either rejects the email or applies permissions for the user account specified on the Access tab.
If you allow record creation by unknown users, choose your settings carefully to make sure the system
applies permissions that allow record creation in the table and fields you have mapped.
For email updates, the system does not check the permissions of the sender unless email parsing is turned
on, which means the updates are applied as dictated by the field mapping without checking any permissions.
This is meant to enable people who were cc'd on the original email to successfully reply to the system even if
they are not loaded as a user. If email parsing is turned on for a reply, then the user must have edit
permissions to both the record and to the fields being updated via parsing.
© 2021 Agiloft Inc. 25Email Parsing
Without email parsing, only the metadata of an email is analyzed for field content. If you want to analyze the
body of the email for relevant information, you can enable email parsing in order to map specific fields from
the main body of the email. Parsing searches for text within defined delimiters that has the format Field
Label: Content, and maps that content to the fields that match the Field Label.
This is mostly useful for receiving emails from other systems, where those emails can be automatically
formatted with the proper syntax. For instance, if you have an event monitoring system and want to create a
support ticket from an event, you might output an email with the proper syntax from the event system that
can be parsed into specified fields in Agiloft.
Generally, REST or SOAP protocols are more reliable for transmitting data between systems than
email, but setting up a parsed email can be simpler.
This article focuses on the usage and behavior of email parsing, which are helpful in deciding whether email
parsing is the best choice for your needs. This information is also helpful for troubleshooting parsing issues or
unexpected behavior. For steps to set up your system to parse emails, refer to Inbound Email Accounts.
Use Cases
Direct Emails: A third-party system generates emails with appropriate formatting for parsing by Agiloft. These
inbound emails are parsed and used to update specific fields in records. If the encrypted ID of an existing
ticket is found in the subject line, the system updates that ticket. Otherwise, the system generates a new
ticket. In either case, the system only updates specific fields if field-specific updates are enabled for that table.
Response Emails: A user responds to an email generated by Agiloft by clicking Reply and editing some fields.
Agiloft parses the response email and updates the modified fields that the user has permission to modify.
The system does not parse email attachments. Attachments are handled according to the Record
Mapping settings for your Inbound Email Accounts.
Group Permissions
Both field- and record-level permissions are applied when updating a record using a parsing format. When an
email is received with parse-friendly formatting, the system checks that the user has permission to edit the
record in question and any fields that are included. If the user has permission to edit to some fields and not
others, only the permitted edits are made.
The system determines the user by finding the first user in the People table with an email that matches the
From: address using a case-insensitive search.
© 2021 Agiloft Inc. 26Parsing Email Types
This section describes how parsing works for different email types.
HTML Emails
Consider the following HTML-formatted example, shown as it appears in the user's email client before
sending. This example includes a header, --Agiloft Detalis; en;--, and footer, --Agiloft Details--
, that match the header and footer defined in the inbound email settings.
Hi there,
I would like to submit an enhancement.
--Agiloft Details; en;--
ID: 8077
My Issue: [I would like to request an enhancement]
Priority: Critical
Summary: Add a parameter "SMTP-Assertion" to the Agiloft-audit email header
Description: Currently Agiloft creates an email. It is not necessary
Status: Open
Date Created: Apr 21 2008 07:27:48
--Agiloft Details--
Thank you.
How does it work?
The email includes several field labels: ID, My Issue, Priority, Summary, Description, Status, and Date Created.
When Agiloft receives a message like this, it parses the text between the specified header and footer, including
formatting:
HTML Source Received
-Agiloft Details; en;--
ID:
8077
© 2021 Agiloft Inc. 27My Issue:
I would like to request an enhancement
Priority:
Critical
Summary:
Add a parameter "SMTP-Assertion"
to the EW-audit email header
Status:
Open
Answer:
Currently the system
creates an email. It is not necessary
Date Created:
Apr 21 2008 07:27:48
-Agiloft Details-
The system searches for matching field labels. If a match is found, and the user has permission to edit the
field, the field is updated with the value from the email.
Parsing relies on a few requirements:
The header and footer must be included in the email, with the language ID at the end of the header, for
Agiloft to accurately parse the contents of the email. This applies to both new emails and replies to
system-generated emails.
The table format should not be modified significantly. Specifically, when Agiloft reads the source HTML,
the following format tags must be kept:
8077
The first is a field label, and the second one is a field value. This has been tested and confirmed to
work with the Microsoft Outlook email client.
© 2021 Agiloft Inc. 28The date format from the original email should be followed. If the original email contains Apr 21 2018
07:27:48, but a reply is sent containing a date such as 07:27:48 1 May 2018 or 07:27:48 06/01/2018, it is
treated as an error.
Plain Text Emails
A plain text email might look like the example below. For a plain text email,, Agiloft parses ^String: as a field label and what follows it as a field value, until the next field label is found on a new
line. The email must include a colon after each field label for the content to be parsed correctly.
--Agiloft Details; en;--
ID: 8077
My Issue: I would like to request an enhancement
Priority: Critical
Summary: Add a parameter "SMTP-Assertion" to
the Agiloft-audit email header
Status: Open
Answer: Currently Agiloft creates an email. It is not necessary
Date Created: Apr 21 2008 07:27:48
--Agiloft Details--
What if I mention a field label inside a field value?
To prevent Agiloft from parsing field labels inside the content intended for other fields, use Tab each time the
content spans multiple lines. If you have external programs that generate emails to the system, configure
those programs to place Tab indentation at the start of each new line of text within a field value. That way, you
have a safeguard in case a line begins with a field label and colon, which might otherwise be parsed
incorrectly.
For example, this plain text email excerpt uses Tab each time the Description value spans a new line:
Description: As we discussed earlier,
based on the conversation with the team,
Priority: Low is no longer correct
Priority: High
This email example would update two fields as follows:
Field New Value
Description As we discussed earlier,
based on the conversation with the
team,
Priority: Low is no longer correct
Priority High
As we discussed earlier,
© 2021 Agiloft Inc. 29What if there are multiple sets of delimiters? Agiloft only parses the first block of text between header and footer markers. For example, in the inbound email below, only the first block regarding ID 8077 is parsed. Hi, Alex We received your letter: -Agiloft Details; en;-- ID: 8077 My Issue: I would like to request an enhancement Priority: Critical Summary: Add a parameter "SMTP-Assertion" to the Agiloft-audit email header Status: Open Answer: Currently Agiloft creates an email. It is not necessary Date Created: Apr 21 2008 07:27:48 -Agiloft Details But found old one from other ticket -Agiloft Details; en;-- ID: 8022 My Issue: it works Priority: Critical Answer: Currently Agiloft is down -Agiloft Details - XML Emails Agiloft can also receive a plain text email where XML syntax is used to distinguish the fields from their values. The format is < Agiloft XML:field label>data. For example: -Agiloft Details; en; XML- 8077 The cup holder in my computer is broken -Agiloft Details- As with the other formats, the system requires the field label instead of the field name. The text "XML" must be included in the header so the system can distinguish XML formatted emails from HTML formatted emails. © 2021 Agiloft Inc. 30
Outbound Email Settings
Outbound email configuration defines the default outbound addresses used for each table and some
characteristics of emails sent by the system or manually by users from within the system. You must have a
valid outbound email address when sending mail, or emails won't be sent. This is important to remember if
you use a field value as the outbound address, rather than an explicit email address. Do not use a field value
unless you can be sure that the field always has a value.
Additionally, emails won't be sent if they contain attachments that are cumulatively larger than the size
defined in the Max Email Attach Size global variable or if the body of the email is larger than the size defined in
the Max Email Body Size (without attachments) global variable. If an email is not sent due to the attachment or
body size, the sender receives an error message. Similarly, even if an email's body size and attachments size
falls within their respective limits, your email won't be successfully sent if its overall size (body and
attachements) exceeds the limits set by your SMTP.
While hosting your knowledgebase on Agiloft servers, you may elect to use "localhost" as your mail server;
however, the spam score calculated and assigned to your mail by receiving servers will be worsened because
the domain of the sending email address doesn't match the domain in the SMTP server name. Hosted servers
do not support IP whitelisting, so if you need to whitelist Agiloft servers, use a Sender Policy Framework (SPF)
to do so.
Configuring Outbound Email
The Outbound Email wizard is used to set up outbound email options on a per-table basis. Those options can
be inherited by subtables, so you may simply set up one set of options for each top-level table and it will apply
to all subtables.
Follow these steps to configure an outbound email account:
1. Go to Setup > Email and SMS > Configure Outbound Email.
2. On the Table tab, select a table.
3. Navigate through all the tabs listed below. Remember that your changes won't be saved until you click
Finish on the final tab.
From Options
On this tab, select options for the source side of communications.
1. Select which groups have access to the email icon on the action bar. Groups without access can still
automatically generate emails through rules and workflow.
© 2021 Agiloft Inc. 312. Configure the default From address for system-generated emails. The From address defines the
account the email originates from in the email header. Note that this can be any address, and it only
gives the appearance of being sent from that sender to the recipient, whose response will be sent to
the Reply-to address.
3. Configure the default Reply-to address for system-generated emails. When email recipients reply to
system-generated emails, their replies are sent to this address, regardless of what appears in the From
address.
4. Next, configure default From and Reply-to addresses for emails manually created by users. Depending
on their permissions, users can override these default addresses manually with an explicit email
address or a selected field linked to an email address. User list and email list fields display all fields of
type Email or Email Pager in the current table, and also include fields that are linked to or copied from
the Login or Full Name field of any sub-table of the Contacts table.
5. Finally, configure the default From address for emails created in the EUI. Typically, users sending emails
from the EUI should be using their own email addresses, so there is a separate default setting for them.
6. Now that you have default From and Reply-to addresses for each scenario, set the address to send
bounced emails to. If the system sends an email that bounces, the bounce notification can be
forwarded to the address selected here. We recommend using a person related to the record, such as
the Assigned Person, rather than sending it back to the table's incoming address because the bounce
notification may strip out the encrypted ID in the subject line, which prevents it from being attached to
the correct record.
7. Configure which groups can see and change the From and Reply-to address for manual emails. In order
to change the From or Reply-to field, users must also belong to a group that has view and edit
permission to the corresponding field in the All Communications table. This option is a way of turning
off access to a particular table while leaving it enabled on others.
8. Click Next.
To Options
On this tab, select options for the target side of communications.
1. Define the default To field for the power and end user interfaces.
2. Choose whether to include the original text when replying to an email.
3. Select the formatting for the original quoted text, if it is included.
4. Choose the default format, HTML or plain text, for outgoing emails.
5. If desired, you can automatically CC or BCC other specified users whenever someone sends an email
from this address.
6. Select any fields you want to include by default in emails going out from this address. If you select any
fields, also select how to interpret permissions when sending field contents:
© 2021 Agiloft Inc. 326.
All Fields includes all fields that the person sending the email has the right to view.
Based on Recipient's Access Permissions sends all fields that both the person sending the email
and the person receiving it have the right to view.
Selected Fields sends the fields selected in the box, provided the sender has view permissions.
7. Choose whether the encrypted record ID is included in the subject line by default. This option can be
overridden in a particular email template or by the user when sending manually. The ID is also
encrypted in the email header, but adding it in the subject line can be useful as a backup in case a
program removes the header information.
8. Choose whether to include a hidden code in the email to allow truncating replies. Including this code
won't automatically truncate replies, which is determined in the inbound email settings, but if you don't
include this code, truncation won't be possible.
9. If this outbound address often sends the same message to multiple people separately, with slight
variations, you might want to enable the option to include a list of recipients in the email. If this is not a
common practice, it's usually best to leave this disabled and use the standard CC line.
10. If necessary, select "Send same email to all recipients" to enforce uniform messages. Note that with this
checkbox selected, all email text is generated based on the first recipient in the To line, and that text is
sent to all other recipients, including any $name variables and SSO hotlinks.
11. Click Next.
Marketing
On this tab, set up marketing for emails if needed, with tracking of email bounces, click rates, and subscribe
requests. For more information, see Email Marketing. If this outbound account won't be used for marketing
communications, simply set the first option to No and click Finish.
If you plan to use an outbound email address for marketing, you'll need a field in the table to store
recipient email addresses, and a second field to store the email's status. Make sure to create those
before you configure the outbound address so you can map to those fields.
If you plan to use this account for marketing, here are all the options:
1. Set Enable Email Marketing on this table? to Yes or No. If you set this to Yes, additional options are
enabled.
2. Choose whether to track sent emails. If you select Yes, Agiloft automatically does the following:
a. Adds a unique one-pixel image to emails. This allows the system to determine if the image was
opened.
b. Tracks if a user clicks on a hotlink to a record.
c. Tracks bounced emails.
3. Select the recipient email field and the email status field from the drop-down menus.
4.
© 2021 Agiloft Inc. 33You can also read
