Table of Contents

Configuration

The configuration is stored in a file named MailGateway.Service.exe.config located in the installation folder. Since the installation folder is usually protected by Windows, administrator privileges are probably necessary to edit the file.

Mail Gateway supports multiple accounts which are unique combinations of an Exchange mailbox, a Lime CRM database and configuration options specific for the account. The support for multiple accounts makes it possible to monitor different mailboxes and import incoming messages into different databases if necessary.

Sample configuration

The following is an example of a typical Mail Gateway configuration file used in a helpdesk solution: 

<configuration>
  <configSections>
    <section name="lundalogik.dataaccess" type="Lundalogik.DataAccess.Configuration.DataAccessConfiguration, Lundalogik.DataAccess" />
    <section name="lundalogik.mailgateway" type="MailGateway.Configuration.MailGatewayConfigurationSection, Mailgateway.Core" />
  </configSections>
  <lundalogik.dataaccess>
    <databases>
      <database name="Lundalogik" accessMethod="WebService">
        <webServiceOptions binding="BasicHttp" address="http://localhost:1337/"/>
      </database>
    </databases>
  </lundalogik.dataaccess>
  <lundalogik.mailgateway>
    <accounts>
      <account>
        <mailbox emailAddress="support@lundalogik.com" userName="lime" password="A super secret password." useOauth2="true" clientId="x11x1111-example-key1-111x-11xx111x11x" tenant="22222xx2-example-key2-x2xx-222x222xxxxx"/>
        <outgoingEmail fromName="Lundalogik Support" fromAddress="support@lundalogik.com">
          <template type="FirstReply" filename="FirstReply.html" subject="Re: %%SUBJECT%% [%%HELPDESK.HELPDESKNO%%]">
            <subtable relationField="history">
              <fields>
                <field name="type" contents="179001" />
                <field name="note" contents="Sent automatic confirmation to customer by email." />
              </fields>
            </subtable>        
          </template>
        </outgoingEmail>
        <table name="helpdesk">          
          <fields>
            <field name="company" contents="%%COMPANY%%" updateExisting="false" />
            <field name="person" contents="%%PERSON%%" updateExisting="false" />
            <field name="title" contents="%%BODY%%" updateExisting="false" />
            <field name="helpdeskno" direction="Out" />
          </fields>
          <subtables>
            <subtable relationField="history">
              <fields>
                <field name="type" contents="179101" />
                <field name="note" contents="Received email from customer, saved as document." />
              </fields>
            </subtable>
            <subtable relationField="document">
              <fields>
                <field name="comment" contents="Email from customer received %%RECEIVEDATE%%" />
                <field name="type" contents="40601" />
                <field name="document" contents="%%MESSAGEFILE%%" />
              </fields>
            </subtable>            
          </subtables>
          <lookup field="helpdeskno" expression="\[(\d+)\]" searchLocation="Subject" />
        </table>
        <filters>
          <filter name="IgnoreInternalSenders" action="Ignore" input="%%FROMADDRESS%%" operator="MatchRegEx" expression=".*@lundalogik\.com$" />
        </filters>
      </account>
    </accounts>
  </lundalogik.mailgateway>
</configuration>

This very basic configuration above tells Mail Gateway to:

Lime CRM Web Service connection
The database and webServiceOptions elements specifies how to talk to the web service and where it is located.
Exchange mailbox
The mailbox element specfifies which mailbox to monitor for incoming messages.
Automatic replies
The outgoingEmail element specifies that an automatic templated reply is to be sent having a subject line consisting of the original subject line with the helpdesk ticket number appended. The following subtable element instructs the service to add a history note whenever that automatic reply is sent.
New helpdesk record
The table element specifies that a new record in the helpdesk table is to be created when a message arrives and to fill the fields of that records with parameters from the message.
New helpdesk history note
The first subtable element beneath the table element specifies that a history note saying that an email was received should be created and linked to the helpdesk record.
New helpdesk document
The second subtable element beneath the table element specifies that a document with the original messages should be created and linked to the helpdesk record.
Update existing records
The lookup element specifies that all incoming messages should have their the subject line scanned for string consisting of six digits in brackets (e.g. [123456]). If a match is found, a check is made whether a corresponding helpdesk record having that ticket number exists. If it does, that record is updated with new information and no new record is created.
Filter messages based on criteria
The filter element instructs the service to ignore all messages sent from addresses ending with @lundalogik.com

Good to know!

Most of the features listed above can be fine-tuned using extra parameters described in detail below.

Web Service settings

This section describes all XML elements and attributes available for configuring the connection to the LIME database via Lime CRM Web Service. Mail Gateway supports connections to different databases for different accounts.

lundalogik.dataaccess

Top element.

Child elements

databases

databases

Container element.

Parent element

lundalogik.dataaccess

Child elements

database

database

Defines the database name.

Parent element

databases

Child elements
Attribute Type Required Default Description
name String Yes N/A A unique identifier for this database that can be used as a reference to it in other parts of the configuration file. Not necessarily the actual database name.

webServiceOptions

Defines options needed for connecting to Lime CRM Web Service.

Parent element

database

Attribute Type Required Default Description
address String Yes N/A Specifies the address used to connect to this database using Lime CRM Web Service.
binding Enumeration No BasicHttp Specifies the binding (protocol) that is to be used for connecting to Lime CRM Web Service. The following values are allowed: BasicHttp, NamedPipes, NetTcp or WsHttp.

Mail Gateway settings

This section describes all XML elements and attributes available for configuring the Mail Gateway service itself.

lundalogik.mailgateway

Top element.

Child elements

global

Contains global settings that affect all accounts.

Parent element

lundalogik.mailgateway

Attribute Type Required Default Description
failedRootDirectory String No N/A Specifies where to save messages that cannot be imported to Lime CRM for some reason. Note that this is a global setting and specifies the base directory where to save problem messages. For each account a sub-directory is created where problem messages specific to that account are stored. Note also that the saveFailedToDisk attribute of the [[#mgw-error-handling|errorHandling]] element must be set to true for this to happen for an account.
messageFormat Enumeration No Eml Specifies which format (Eml or Msg) to use when saving messages to disk or as LIME documents.
debugLogging Boolean No False Specifies whether or not to enable debug logging. When enabled, verbose log output is saved to a text log file in C:\ProgramData\Lundalogik\Mail Gateway.
proxyUrl String No N/A Specifies the URL of the proxy server to use. No proxy server is used if left out or blank. Note! The proxy server must support HTTP 1.1.
proxyPort Integer No 80 Specifies which port to use when connecting to the proxy server.
proxyBypassOnLocal Boolean No False Specifies whether or not to bypass the proxy server when connecting to addresses on the local network.

accounts

Contains one or more accounts that each correspond to a mailbox.

Parent element

lundalogik.mailgateway

Child elements

account

This element contains all stand-alone configuration options for an account.

Parent element

accounts

Child elements
Attribute Type Required Default Description
checkInterval Integer No 120 The number of seconds to wait between each attempt to check the mailbox for new messages.
database String No N/A The name of the Lime CRM database to use with this account. This is not necessarily the actual database name, it just have to match the name of the database as specified in the lundalogik.dataaccess section. If not specified the database having the default attribute set to true is used.

mailbox

Configures the connection to Exchange Web Services, for example which mailbox to use with this account.

Parent element

account

Attribute Type Required Default Description
emailAddress String Yes N/A The email address of the mailbox to monitor, e.g. info@lundalogik.se. Must be an actual mailbox, not an alias.
userName String No N/A The name of a user with full privileges on the mailbox specified by the emailAddress attribute. If not specified the credentials of the currently logged on Windows user (typically the user running the Mail Gateway Windows service) will be used for authentication.
password String Yes N/A The password corresponding to the user specified by the userName attribute.
serviceUrl String No N/A Full URL to the Exchange Web Service to use. If not specified automatic discovery will be used to detect the correct address. Should usually not have to be specified.
impersonate Boolean No False Whether to use Exchange impersonation to connect to the mailbox.
useOauth2 Boolean No False Whether to use Oauth2 authentication with Azure AD.
clientId String No N/A The client/application identifier of the Azure AD application when using Oauth2 authentication.
tenant String No N/A The tenant identifier associated with the Azure AD application when using Oauth2 authentication.

Note: when using Oauth2 authentication with Azure AD, the following attributes should be specified: emailAddress, userName, password, useOauth2, clientId, tenant.

profile

Mailbox configuration options for when using MAPI for connecting to Exchange. Cannot be used with the mailbox element.

Warning!

Use of MAPI is strongly discouraged and is to be considered deprecated.

Parent element

account

Attribute Type Required Default Description
name String Yes N/A A unique identifier for this mailbox. Content not important as long as it is unique.
server String Yes N/A Name of the Exchange server machine that the mailbox resides on.
mailbox String Yes N/A Name of the Exchange mailbox to use (not the email address).

errorHandling

Options for configuring how Mail Gateway operates when an incoming email message cannot be imported for some reason.

Parent element

account

Attribute Type Required Default Description
retries Integer No 3 Specifies the maximum number of times Mail Gateway should try to import a message.
minutesBetweenRetries Integer No 5 Specifies the number of minutes to wait before trying again if a message cannot be imported.
saveFailedToDisk Boolean No False Specifies whether messages that cannot be imported (after the maximum number of retries) should be simply ignored and left in the mailbox or saved to disk and then deleted from the mailbox.

security

This element contains options for configuring how Mail Gateway treats incoming messages in respect to security.

Parent element

account

Attribute Type Required Default Description
removeAttachments Boolean No True If Mail Gateway is configured to store incoming messages as documents, this option specifies whether or not attachments are removed from the messages before it is saved in Lime CRM. Email attachments can contain malicious code.

Warning!

Default value will remove attachments.

webServiceAllowed Boolean No False

Warning!

Deprecated and should not be used, will be removed in a future release.

Specifies whether incoming messages having a body that seems to be valid XML should be directly forwarded to the Lime CRM Web Service.

table

Parent element

account

Child elements
Attribute Type Required Default Description
name String Yes N/A The name of the Lime CRM database table that records should be created in when a message is receieved, e.g. helpdesk.

subtables

Container element.

Parent elements
Child elements

subtable

Parent element

subtables

Child elements

fields

Attribute Type Required Default Description
relationField string Yes N/A The name of the relation field in the table specified by the the table element that points to another table where linked records should be created. For example, if a history note record should be created when an email message related to a helpdesk ticket is received this attribute should be set to the name of the relation field in table helpdesk.
attachmentTemplate Boolean No False When set to true, this subtable entry will enable import of individual email attachments. For every attachment a new record will be created in this table according to field specification.

fields

Container element.

Parent elements
Child elements

field

field

Parent element

fields

Attribute Type Required Default Description
name string Yes N/A The database name of the field to read or write from/to.
contents string No Empty string. A static string, dynamic contents (in the form of a field code), or both. Can also be left empty to empty the field of data..
direction Enumeration No In In specifies that data should be written to Lime CRM, Out means that data should be read from Lime CRM (for use in templates, for example). Valid values: In or Out.
updateExisting Boolean No False Specifies whether or not to overwrite any existing value when a database record is updated. Set to true to always update the value in Lime CRM regardless of whether a new record is created or an existing one updated.
defaultValue String No N/A Optionally specifies a value to use if the new record value is an empty string. Typically used to prevent problems when a field in the database is mandatory but data from incoming messages could be empty (e.g. the subject line).

lookup

Parent element

table

Attribute Type Required Default Description
field string Yes N/A The database name of the field that should be used for looking up existing records.
expression string Yes N/A Specifies the regular expression that should be used for searching incoming messages after a keyword that is used to search in the field specified by the field attribute. An example of a regular expression is: \[([A-F\d]{8})\]. Using this expression instructs Mail Gateway to look for exactly eight digits or upper case letters in the range A - F that are enclosed in brackets. The service extracts any matching information in the first group (indicated by the blue parenthesis above) found by the regular expression.
searchLocation Enumeration No SubjectAndBody Specifies which parts of the incoming message to search for the lookup expression. Valid values: Subject, Body or SubjectAndBody.

outgoingEmail

Parent element

account

Child element

template

Attribute Type Required Default Description
fromName String No Exchange display name Specifies the name, e.g. John Doe, that outgoing email messages should appear as being sent from.

Note!

This setting is not always respected by the Exchange Server. In those cases the recommended solution is to change the default display name of the mailbox to the desired sender name.

fromAddress String Yes N/A Specifies the email address, e.g. john.doe@example.com, that outgoing email messages should be sent from.
markAsAutoGenerated Boolean No True Specifies whether or not outgoing messages should include a header that indicates that the message has been automatically generated. By doing this automatic replies such as out-of-office notices are often not sent back by email servers, which is a good thing for us.
useEmptyReturnPath Boolean No True Specifies whether or not outgoing messages should be sent with an empty return path. When using an empty return path it is less likely that automatic replies such as out-of-office notices are sent back by email servers, which is also a good thing for us.

template

Parent element

outgoingEmail

Child element

subtable

Attribute Type Required Default Description
type Enumeration Yes N/A Specifies when this template is used. FirstReply means that the template is to be used when for example a new helpdesk ticket is created. FollowUp templates are used when Mail Gateway has been able to look up an existing record. Valid values: FirstReply or FollowUp.
filename String Yes N/A Specifies the name of the file containing the mail template relative to the C:\ProgramData\Lundalogik\Mail Gateway\Templates folder.
subject String No N/A Specifies the subject to use for outgoing messages. May contain field codes. If using a .msg file as a template this attribute has precedence over the subject specified in the .msg file. Must always be set for HTML templates.

senderIdentification

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:
All Mail Gateway will use all methods available described here)
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.

filters

Container element. Note that filters are run in the order they are defined.

Parent element

account

Child elements

filter

filter

Defines a message filter.

Parent element

filters

Attribute Type Required Default Description
name String Yes N/A A unique name that describes this filter.
input String Yes N/A Specifies what part of an incoming message to look at when deciding whether or not to apply the filter to the message. Typically a field code is used here, for example %%FROMADDRESS%%.
operator Enumeration Yes N/A Specifies which operator to use when comparing the input data specified by the input attribute. Valid values: MatchRegEx, Equal, NotEqual, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual.
expression String Yes N/A The expression that the data specified by the input attribute is compared against using the operator specified by the operator attribute. This can either be a regular expression if the operator attribute is set to MatchRegEx or otherwise a static string expression.
action Enumeration Yes N/A Specifies the action to take if the message matches the filter. Valid values: None, Ignore, Delete, DontReply or NextFilter.
inputEmptyAction Enumeration No NextFilter Specifies the action to take if the filter input data is empty or missing. Typically used to take a different action if for example a message header is missing. Valid values: None, Ignore, Delete or NextFilter.