Email 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.
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.
Parsing 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:
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:
<td class="SIEmailData">8077</td>
The first <td> 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.
- The 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 <NEW LINE>^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, <TAB>based on the conversation with the team, <TAB>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, |
| Priority | High |
What 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</ Agiloft XML field label>.
For example:
-Agiloft Details; en; XML- <Agiloft XML:ID>8077</Agiloft XML:ID> <Agiloft XML:Description>The cup holder in my computer is broken</Agiloft XML:Description> -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.