Concepts

In a helpdesk solution it is common that a customer or user gets back with more information regarding an already existing helpdesk ticket. Because of this updating existing records or adding more information to existing records is supported. Mail Gateway however needs to know how to associate an incoming message with a record that already exists in the database. This is done by scanning the message for a known signature, for example a ticket number in a known format enclosed in brackets. If the number can be extracted from the message a database lookup is performed against a given field and if a unique match is returned that matching record is updated.

A common method to enable lookups is by appending the unique reference number (e.g. ticket number, key) by embedding a field code in the subject line of outgoing messages sent by Mail Gateway.

Read more about lookups in the configuration reference.

To provide a dynamic experience Mail Gateway supports field codes in several places in the configuration. A field code is a placeholder for information that for example depends on the contents of an incoming message. A common scenario is that the subject line of the incoming message is to be imported into a specific field of record in the Lime CRM database. This is achieved by specifying that the field code %%SUBJECT%% is to be used as data source for that particular field. Field codes can also be used in outgoing message templates so that the content of those messages can be dynamic.

The following field codes are available for use:

Field code Description
%%BODY%% Message body.
%%SUBJECT%% Subject line.
%%RECEIVEDATE%% The date that the message was received.
%%RECEIVEDATETIME%% The date and time that the message was received.
%%CURRENTDATE%% The current date in yyyy-mm-dd format.
%%CURRENTDATETIME%% The current date in yyyy-mm-dd hh:mm:ss format.
%%FROMADDRESS%% The sender's email address.
%%FROMNAME%% The sender's display name.
%%TOADDRESSES%% The recipient's email address. In case there are more than one recipient, addresses are semi-colon separated.
%%MESSAGEFILE%% The entire message in binary format. Can only be used with document fields.
%%ATTACHMENTNAME%% File name of an attachment. Can only be used in attachment templates.
%%ATTACHMENTFILE%% File data of an attachment. Can only be used in attachment templates.
%%COMPANY%% The ID of the sender's company record, if possible to determine.
%%PERSON%% The ID of the sender's person record, if possible to determine.
%%COWORKER%% The ID of the sender's coworker record, if possible to determine.
%%HEADER:NameOfInternetHeader%% The contents of the internet header specified. Makes it possible to for example create filters that acts on the contents of an internet header.

Mail Gateway can be configured to automatically respond to incoming messages. What is sent back to the sender of the original message is defined through templates. For each account two different templates can be configured, one that is used when a message import leads to the creation of a new record and another that is used when an existing record is updated. This makes it possible to send a message saying “We have registered your helpdesk ticket and assigned it ticket number ABC123” in the first case and another saying “Thank you for providing more information regarding your ticket having number ABC123”.

Templates can be in either HTML or .msg format, where HTML is strongly recommended since there are less issues with plain text files. It is possible to use field codes in templates, thereby making it possible to use dynamic content in outgoing messages, as “ABC123” in the example above. Using field codes in message templates is a bit different than in other places. Example:

Dear Sir/Madam,
We have received your email and will start working on solving your problem as soon as possible.
Your case has been assigned ticket number HELPDESK.HELPDESKNO, please refer to this number if contacting >us regarding this case in the future.

A field code in message templates consists of the name of the table (helpdesk in this example) followed by a dot and the name of the field (helpdeskno above), enclosed in %%. Note that the field used must have its direction attribute set to Out for it to be available for use like this. Refer to the configuration reference for more information.

When using HTML templates it is possible to embed images in outgoing messages. The image file to be embedded needs to be located in the same folder as the template and the appropriate HTML markup needs to be present in the template file, for example:

<img src="image.png" />

Tip!

If images must be used, make sure that the total file size is kept down to minimize message download times.

Warning!

Embedding images increases the possibility that outgoing messages are classified as spam by the receiving end.

Contains options for how Mail Gateway should attempt to associate company and/or person records with the sender of an incoming message. Matches on email, you must set a link-field with label “Email” for Mail Gateway to match against that field.

Parent element

account

Attribute Type Required Default Description
method Enumeration No All Defines which method(s) to use when the field codes %%COMPANY%% and %%PERSON%% are used. Valid values:
PersonEmailDomain Will use methods 1, 2, 3, 4 and 5.
CompanyEmailWebsite Will use methods 1, 2, 3 and 4.
CompanyEmailDomain Will use methods 1, 2 and 3.
CompanyEmailExact Will use methods 1 and 2.
PersonEmailExact Will only use method 1.
person.company String No N/A Usually the relation between the person and company tables in the database is automatically detected by looking at database metadata (e.g. labels, relations). However, if there are several relations between the person and company tables Mail Gateway will not be able to decide which one to use. In that case, specify the name of the company field in the person table that should be used for the association.

Mail Gateway will automatically try to look up company and person records matching the sender of an incoming message when the field codes %%COMPANY%% and %%PERSON%% are used. Optionally, looking up coworkers is also supported by using the %%COWORKER%% field code. This information can be used when populating a database record so that relations are set automatically. Mail Gateway uses database metadata such as relations, table and field labels to try to identify the matching company and person records. The following search order is used if not explicitly specified in the configuration:

Company

  1. If a person has already been found using exact address matching as described below, use the company associated with that person.
  2. Match the sender's full email address with the company email address.
  3. Match the domain name in the sender's address with the company email address.
  4. Match the domain name in the sender's address with the domain name of the company's web site.
  5. Search for persons in the database having the same domain name in their email address as in the sender's address and only one result is returned, use that company.

Person

  1. Match the sender's email address exactly.

Mail Gateway has a built in filter chain that each incoming message is run through before being processed. Typical uses of message filter is for example:

  • Ignoring messages sent from a specific domain if those messages should be processed manually.
  • Deleting messages having a spam level header above a certain level.

The outcome of the filtering process can be one of the following:

None
Do not run any more filters and continue processing the message as usual.
NextFilter
Proceed with the next filter in the chain.
Ignore
Mark the message with the ignore flag which means that Mail Gateway will never look at it again (unless reset using the Mailbox Reset tool). No more filters are run.
Delete
Delete the message and do not run any more filters.
DontReply
Suppress any replies to this message.

Mail Gateway can be configured to handle email attachments in three ways:

  • Discard attachments. Usually as a security measure by configuring the removeAttachments attribute of the security element in the configuration file.
  • Embedded attachments. Original attachments are embedded in the .msg or .eml file containing the original message and saved as a document in Lime CRM.
  • Extracted attachments. Original attachments are extracted from the incoming message and are stored as individual documents in Lime CRM.

The extract individual attachments, use a subtable configuration similar to this:

<subtable relationField="document" attachmentTemplate="true">
  <fields>
    <field name="description" contents="%%ATTACHMENTNAME%%" />
    <field name="document" contents="%%ATTACHMENTFILE%%" />
  </fields>              
</subtable>

The attachmentTemplate attribute instructs Mail Gateway to create a new record for every attachment in the original message and map the fields according to the elements in the fields element collection.

If an error somehow occurs when Mail Gateway is importing an incoming message different action is taken depending on the error handling configuration.

The default behavior (the saveFailedToDisk attribute set to false) is to try again up to the number of times specified in the configuration. If the message still has not been possible to import, the message will be left in the mailbox and ignored by Mail Gateway for all future (unless the ignore flag is reset using the Mailbox Reset tool).

If the saveFailedToDisk attribute is set to true messages will after the specified number of attempts be saved to disk in the folder specified in the configuration and deleted from the mailbox.

  • Last modified: 10 months ago
  • by Gustav Stigestadh