====== 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:

<code xml>
<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>
</code>
                    
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
  
<WRAP round tip>
=== Good to know! ===
Most of the features listed above can be fine-tuned using extra parameters described in detail below.
</WRAP>

===== 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]]

==== database ====
Defines the database name.

== Parent element ==
[[#databases]]

== Child elements ==
  * [[#webServiceOptions]]

^ 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|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]]
  * [[#accounts]]

==== 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]]

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

== Parent element ==
[[#accounts]]

== Child elements ==
  * [[#mailbox]]
  * [[#profile]]
  * [[#errorHandling]]
  * [[#security]]
  * [[#table]]
  * [[#outgoingEmail]]
  * [[#senderIdentification]]
  * [[#filters]]

^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 [[https://msdn.microsoft.com/en-us/library/office/dn722377(v=exchg.150).aspx|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.

<WRAP round important>
=== Warning! ===
Use of MAPI is strongly discouraged and is to be considered deprecated.
</WRAP>

== 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. <WRAP round important> === Warning! === 
Default value will remove attachments.</WRAP>  |
|webServiceAllowed  |Boolean  |No  |False  | <WRAP round important> === Warning! === 
Deprecated and should not be used, will be removed in a future release.</WRAP> 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 ==
  * [[#fields]]
  * [[#subtables]]
  * [[#lookup]]

^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 ==
  * [[#table]]
  * [[#template]]

== Child elements ==
  * [[#subtable]]

==== 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 ==
  * [[#table]]
  * [[#subtable]]

== 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 [[addons:mail-gateway:concepts:#Field codes|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 [[http://en.wikipedia.org/wiki/Regular_expression|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. <WRAP round info>
=== 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.</WRAP> |
|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 [[addons:mail-gateway:concepts#Field codes|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 [[addons:mail-gateway:concepts#Field codes|field codes]] ''<nowiki>%%</nowiki>COMPANY<nowiki>%%</nowiki>'' and ''<nowiki>%%</nowiki>PERSON<nowiki>%%</nowiki>'' are used. Valid values: |
| ::: | ::: | ::: | ::: | **All** Mail Gateway will use all methods available [[addons:mail-gateway:concepts#Sender identification|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 [[addons:mail-gateway:concepts#Field codes|field code]] is used here, for example ''<nowiki>%%</nowiki>FROMADDRESS<nowiki>%%</nowiki>''.   |
|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 [[http://en.wikipedia.org/wiki/Regular_expression|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//.    |